I am trying to write a Open API specification with Swagger-ui (swagger version 2.0) and I am not sure how to represent a POST parameter with a path parameter
POST /ping/{text}
My specification is as follows,
# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
title: Mock API
description: Mock API
version: "1.0.0"
# the domain of the service
host: api.mock.com
# array of all schemes that your API supports
schemes:
- https
# will be prefixed to all paths
basePath: /v1
produces:
- application/json
paths:
/ping:
get:
summary: Ping
description: |
Respond to PING requests, similar to heart beat
parameters:
- name: path
in: path
description: String input for echo service
required: false
type: string
tags:
- ping
responses:
200:
description: The text passed in the request
schema:
type: string
default:
description: Empty response for request passed
schema:
type: string
And the swagger ui shows an error as follows -
code: "ONE_OF_MISSING"
message: "Not a valid parameter definition"
but if I change it to in: query the error vanishes. What am I doing wrong? or what is the right way to specify a path parameter in open API specification?
There are a few changes you need to make to your document to conform to the Open API specification.
1- The name field should match the path segment (ie text
If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object. See Path Templating for further information.
2- required: true should be added.
If the parameter is in "path", this property is required and its value MUST be true.
3- If you want to document POST /ping/{text}, get needs to be changed to post. Also the path segment (ie. /{text) should be added to the path.
Here is the final Swagger doc after the changes described above:
# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
title: Mock API
description: Mock API
version: "1.0.0"
# the domain of the service
host: api.mock.com
# array of all schemes that your API supports
schemes:
- https
# will be prefixed to all paths
basePath: /v1
produces:
- application/json
paths:
/ping/{text}:
post:
summary: Ping
description: |
Respond to PING requests, similar to heart beat
parameters:
- name: text
in: path
description: String input for echo service
required: true
type: string
tags:
- ping
responses:
200:
description: The text passed in the request
schema:
type: string
default:
description: Empty response for request passed
schema:
type: string
According to the specification it seems that "required" has to be true if you set "in: path".
Details can be found here: http://swagger.io/specification/#parameterObject
Related
For one particular endpoint in OpenAPI v3 spec, I need to manually handle request mime-type. It's a GET request, where the user should specify Accept header, and the service loads some data and encodes it into one of multiple supported formats to respond with. I'm trying to specify Accept and Content-Type in spec:
/example:
get:
description: Example endpoint
operationId: example
parameters:
- name: Accept
in: header
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
type: string
format: binary
headers:
Content-Type:
description: Content type
schema:
format: string
'404':
description: Not found
'406':
description: Unsupported mime-type
But codegen tool print warnings:
WARN Accept is described separately and will be ignored in this section {"at": "spec.yml:96:11"}
WARN Content-Type is described separately and will be ignored in this section {"at": "spec.yml:111:15"}
and doesn't generate these headers in code.
How should I pass these dynamic params to request and response?
I don't want to describe all supported mime-types in spec, because the list of supported formats may change dynamically without changing the code, and I don't want need to recompile the server every time I add or remove new mime-type encoder.
I'm testing an API Gateway setup on Google Cloud to access specific endpoints on a service deployed on Cloud Run. I'm following the steps shown here. We need to authenticate using an API Key, so the API Key specific configuration that went into the API Gateway config was picked from this documentation.
The API Gateway config is as shown below:
# api_gateway_config.yaml
swagger: '2.0'
info:
title: myappapi
description: API with Cloudrun Backend
version: 1.0.0
schemes:
- https
produces:
- application/json
paths:
/:
get:
summary: Greet a User from service
operationId: hello
x-google-backend:
address: https://myappapi-asldfjoiewjfv-uc.a.run.app/
security:
- api_key: []
responses:
'200':
description: A successful response
schema:
type: string
/reports/results/{id}:
get:
summary: Get Report Results for specified report id
operationId: GetReportResults
x-google-backend:
address: https://myappapi-asldfjoiewjfv-uc.a.run.app/v1/reports/results/{id}
parameters:
- in: path
name: id
required: true
type: integer
security:
- api_key: []
responses:
'200':
description: A successful response
schema:
type: string
securityDefinitions:
# This section configures basic authentication with an API Key.
api_key:
type: "apiKey"
name: "key"
in: "query"
For a sample call to the /reports/results endpoint as http://myappapi/reports/results/1,
the expectation is for calls to get converted to https://myappapi-asldfjoiewjfv-uc.a.run.app/v1/reports/results/1?key=MyAPIKeyHere. But instead they turn out as https://myappapi-asldfjoiewjfv-uc.a.run.app/v1/reports/results?key=MyAPIKeyHere&id=1
Is there a way to get the API calls go as https://myappapi-asldfjoiewjfv-uc.a.run.app/v1/reports/results/1?key=MyAPIKeyHere ?
Thanks in Advance!
As mentioned in this documentation
Set path_translation as part of setting x-google-backend:
x-google-backend:
address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]
The default value of path_translation depends on where you set x-google->backend in your OpenAPI spec:
When x-google-backend is used at the top level of the OpenAPI specification, path_translation defaults to APPEND_PATH_TO_ADDRESS.
When x-google-backend is used at the operation level of the OpenAPI specification, path_translation defaults to CONSTANT_ADDRESS.
For more details on path translation, please see the Understanding path translation section. You can also check this stackoverflow thread.
I am new to using openapi 3. I use the code from the link. I'm wondering if it's possible to check if I inserted a user with the same email?
The link you referred is poining to the default swagger editor which contains pet store specification. If you have modified in that it must be in your local browser and does not reflect to others.
OpenApi is a specification so you can define apis which can check email id exists or not as shown below and you can generate server side code using the code generator, but the implementation has to be provided by you in the language you are working on such as java, python...
paths:
/checkEmailId:
get:
summary: Check an email already exists
operationId: checkEmailId
tags:
- email
parameters:
- name: emailId
in: query
description: emailId
required: true
schema:
type: string
responses:
'200':
description: If email does not exist
content:
application/json:
schema:
....
I have an HTTP 302 (Redirect) that I implemented a new status parameter, that will append to the RedirectURL, so one can show a message something like
if the call URL is passed as
GET http://localhost:8080/info/status?redirectUrl=http://localhost:8080/redirect
then it will redirect as
http://localhost:8080/redirect?status=success
and it's counterpart
http://localhost:8080/redirect?status=error
but how does one describe this in OpenAPI specification? I can't seem to make use of parameters in the response and found some code that uses responseParameters but I had no luck to make it work... don't even know if it's something that is supported, at least, I get no errors compiling with both commands
/info/setup:
get:
summary: Setup Url
description: Setup Url to create new setup. Should be retrieved from api
apps endpoint and redirect to, not called directly by the url defined
here
parameters:
- in: query
name: installationId
description: The installation id
required: true
schema:
type: string
- in: query
name: redirectUrl
description: Url to redirect back to upon finished installation
required: true
schema:
type: string
responses:
"302":
description: Redirect
responseParameters:
- in: query
name: status
description: the status of the instalation
schema:
oneOf:
- type: string
example: success
description: When the installation was successful
- type: string
example: error
description: When the installation was erroneous
headers:
location:
description: Setup state based redirect
schema:
oneOf:
- type: string
description: If setup is done and valid for installation id, will
redirect to given redirect url
- type: string
description: If no setup exist for installation id, will redirect to
SumUp oauth page
- type: string
description: If error during authorization with SumUpl, e.g. non
matching editions, will redirect to a setup page for
further user action
what is the common way of having such a scenario?
should we have 2 redirect URLs like
GET http://localhost:8080/info/status
?redirectUrl=http://localhost:8080/redirect
&errorUrl=http://localhost:8080/redirect_error
I'm a bit of a loss on this simple predicament, maybe someone can help 😊
Yes, this is an annoying issue with OpenAPI. You cannot really specify a redirect explicitly.
The best you can do is specify a response with a status code in the 3xx redirect range (301, 302, 303, 307, 308) that has a "location" header parameter of type "string".
You should then add a description and summary - pretty much what you have already done.
There is this issue in the OpenAPI specification github: https://github.com/OAI/OpenAPI-Specification/issues/2512
Hopefully something will be done soonish.
I have a new OpenAPI setup via SwaggerHub. Is there an option to force a certain Accept header globally?
I have set up the Content-Type on the response:
openapi: 3.0.0
paths:
/test-path:
get:
responses:
'200':
description: OK
content:
application/vnd.company.v1.0.0+json:
When inserting a different Accept header via cURL request, the following out is made:
{"message":"Missing matching response for specified Accept header"}
That makes sense, since we aren't providing any response for that.
Unlike OpenAPI/Swagger 2.0, which has global consumes and produces, OpenAPI 3.0 requires that request and response media types be defined in each operation individually. There's no way to define the Content-Type or requests or responses globally.
You can, however, $ref common response definitions (such as error responses), which can reduce the repetition.
openapi: 3.0.2
...
paths:
/foo:
get:
responses:
'400':
$ref: '#/components/responses/ErrorResponse'
/bar:
get:
responses:
'400':
$ref: '#/components/responses/ErrorResponse'
components:
responses:
ErrorResponse:
description: An error occurred
content:
application/vnd.error+json:
schema:
...