I am writing an API YAML that returns an MP3 file. I am not familiar with multimedia responses. While going through Google I found that I can use the audio/mp3 content type. But I couldn't find any example showing how to do it. How should I address this audio content type?
OpenAPI 3.1
A binary file response is defined with just the media type and no schema:
openapi: 3.1.0
...
paths:
/something:
get:
responses:
'200':
description: An audio file
content:
audio/mp3: {}
OpenAPI 3.0
Files are defined as binary strings (type: string + format: binary):
openapi: 3.0.3
...
paths:
/something:
get:
responses:
'200':
description: An audio file
content:
audio/mp3:
schema:
type: string
format: binary
OpenAPI 2.0
Binary file responses are defined with a type: file schema. Make sure to also specify the media type in the operation's produces list:
swagger: '2.0'
...
paths:
/something:
get:
produces:
- audio/mp3
responses:
200:
description: An audio file
schema:
type: file
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 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 am trying to create an OpenAPI 3.0 definition for an existing API. It has a POST operation and takes header values as the input. Request body is empty. However the backend API was coded very poorly and is expecting request header Content-Type: application/json even though the body is empty.
How do I achieve this in OpenAPI 3.0? Looks like Content-Type is not accepted as a valid header parameter in OAS 3.0.
You can add the requestBody with the application/json media type but no schema.
openapi: 3.0.2
...
paths:
/something:
post:
parameters:
...
requestBody:
content:
application/json: {}
with Insomnia when use:
requestBody:
content:
application/json: {}
result is this: (preview)
but if use this:
requestBody:
content:
application/json:
schema: # Request body contents
type: object
result is : (preview)
Based on Open API 3 spec, your requestBody should be like the following:
requestBody:
required: true
description: blabla.
content:
application/json:
schema:
type: object
nullable: true
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:
...
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