I have an endpoint which returns an image in response and I would like the swagger documentation to return and display the image within the framework.
I've looked at the documentation here and here and tried all three examples all which have no success.
Am I trying the impossible?
Here is my example
paths:
"/qrcodes/{string_to_encode}":
get:
tags:
- QR Code
summary: A QR code generation endpoint
parameters:
- name: string_to_encode
in: path
required: true
description: URL encoded string to convert to a QR code
schema:
type: string
responses:
'200':
description: OK
content:
application/png:
schema:
type: string
format: binary
The generated curl also warns about binary output
Change application/png to image/png. Other than that, your definition is correct.
Related
I'm writing an Open API 3.0 spec and trying to get response links to render in Swagger UI v 3.18.3.
Example:
openapi: 3.0.0
info:
title: Test
version: '1.0'
tags:
- name: Artifacts
paths:
/artifacts:
post:
tags:
- Artifacts
operationId: createArtifact
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
201:
description: create
headers:
Location:
schema:
type: string
format: uri
example: /artifacts/100
content:
application/json:
schema:
type: object
properties:
artifactId:
type: integer
format: int64
links:
Read Artifact:
operationId: getArtifact
parameters:
artifact-id: '$response.body#/artifactId'
/artifacts/{artifact-id}:
parameters:
- name: artifact-id
in: path
required: true
schema:
type: integer
format: int64
get:
tags:
- Artifacts
operationId: getArtifact
responses:
200:
description: read
content:
application/octet-stream:
schema:
type: string
format: binary
renders a link like this:
Is this expected? I ask because the operationId is exposed on the UI and parameters is shown as a JSON reference make it seem like something is not displaying properly. I would have expected a hyperlink or something to take me to the appropriate section in the Swagger web page that corresponds to the API being referenced by the link.
Yes this is how Swagger UI currently renders OAS3 links. Rendering of links is one of the things on their OAS3 support backlog:
OAS 3.0 Support Backlog
This is a collection ticket for OAS3 specification features that are not yet supported by Swagger-UI.
...
[ ] Links can't be used to stage another operation
[ ] Link-level servers are not available for executing requests
I use online Swagger Editor with OpenAPI 3.0 and I have to create a definition file download. I develop server-side and a customer should be able to create a client using YAML description without my "addition explanation". The relevant part of YAML is:
/files/download/{fileName}:
get:
summary: download file
operationId: downloadFile
description: this API is for file download
parameters:
- in: path
name: fileName
schema:
type: string
required: true
description: The name of file to download
responses:
200:
description: Operation performed successfully.
content:
application/octet-stream:
schema:
type: string
format: binary
...
The questions are:
Content. Currently, it is defined as octet-stream as a most common type, but actually, it depends on the type of a file from some predefined set of file types. Is there any way to define such kind of mapping (file type/content type) and use it with a content tag?
The response header should include a key/value pair attachment or inline and file name. The file name is defined in path - {fileName}. Is there any way to describe the concatenation of enum {attachment, inline} and the value of fileName?
I believe content is what you're looking for. You can also use contentReference to reference a reusable object in components.
For example:
paths:
/files/{fileName}:
get:
summary: download file
operationId: downloadFile
description: this API is for file download
parameters:
- in: path
name: fileName
schema:
type: string
required: true
description: The name of file to download
responses:
200:
description: Operation performed successfully.
content:
application/pdf:
schema:
type: string
format: binary
components:
contentTypes:
application/pdf:
schema:
type: string
format: binary
I'm using Swagger Editor with OpenAPI 3.0. I need to document a route which consists of uploading an image. When attempting to "Try it out", I don't get the file browser to choose the image to upload in the request body, all I get is a JSON string with the name and type of parameter.
This is the YAML description of the route:
openapi: 3.0.0
...
paths:
/media/upload/thumbnail:
post:
tags:
- media
- publications
security:
- bearerAuth: []
summary: upload a kid's publication
operationId: uploadPublication
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
upload:
type: string
format: binary
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: ObjectId of the uploaded file in db (original size)
example: 5a6048b3fad06019afe44f24
filename:
type: string
example: myPainting.png
thumbnail:
type: string
description: ObjectId of the uploaded file in db (thumbnai size)
example: 5a6048b3fad06019afe44f26
'400':
description: Authentication failed
What am I missing here?
Your definition is correct.
Support for file upload for multipart/form-data requests in OpenAPI 3.0 definitions has been added in Swagger Editor 3.5.7 and Swagger UI 3.16.0. Make sure you are using a version that supports file upload.
For one of my same kind of concern !!!
I had to modify the input type to requested endpoint method.
Note- It might not address all type of requirements, but few can definitely be benefitted from this
Before:
/myEndpoint( #RequestBody RequestModelName requestModelName )
where RequestModelName has properties and getter/setter...
private MultipartFile file
private String otherProp
By this I could NOT see File option in swagger.
After:
/myEndpoint( #RequestParam MultipartFile file, #RequestParam String otherProp )
And then I could see File option in swagger...
Try with
content:
image/png:
schema:
properties:
file:
type: string
format: binary
I am starting a REST service, using Swagger Codegen. I need to have different responses for different parameters.
Example: <baseURL>/path can use ?filter1= or ?filter2=, and these parameters should produce different response messages.
I want my OpenAPI YAML file to document these two query params separately. Is this possible?
It is not supported in the 2.0 spec, and not in 3.0 either.
Here are the corresponding proposals in the OpenAPI Specification repository:
Accommodate legacy APIs by allowing query parameters in the path
Querystring in Path Specification
If you're still looking, I found out a way around this problem. It's a bit of a hack, but it works.
Basically, you can have two definitions to the same path by adding a slash (/) in the URL.
That way, you can set a response for <baseURL>/path with the ?filter1= parameter and set another response for <baseURL>//path with the ?filter2= parameter. It's also important that you give an unique operationId for each of the definitions.
paths:
/path/you/want:
get:
summary: Test
operationId: get1
parameters:
- name: filter1
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeResponse'
/path/you//want:
get:
summary: Another test
operationId: get2
parameters:
- name: filter2
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeOtherResponse'
I tried this with a path parameter and it worked just fine!
In swagger defining location,type explicitly is what defines these variables.
You have all the required fields to avoid collision of variables, for a json body you have to reference a declaration or use an example schema as shown below. For my case I have used a schema example rather than a declaration reference
/auth/account/password/reset/{userId}/{resetToken}:
post:
consumes:
- application/json
parameters:
- in: path
name: userId
type: string
required: true
- in: path
type: string
name: resetToken
required: true
- in: header
name: authorization
required: true
type: string
- in: body
name: body
required: true
schema:
type: object
example:
password: password
confirmPassword: password
responses:
"200":
description: OK
In Swagger you can add ? to make endpoints different.
i.e. /articles and /articles?:
When using ? in Swagger editor you will see error:
However on your final Swagger page there will be mark VALID
Additional information:
Remember about unique operationId for duplicated entries
I have a get call in my swagger REST API that needs to return a pdf file. There is no clear example / documentation on how to do this without causing a syntax error.
responses:
200:
description: Returns PDF
schema: [application/pdf]
and
responses:
200:
description: Returns PDF
schema:
type: file
and
responses:
200:
description: Returns PDF
schema:
type: [application/pdf]
all fail. Is this even possible?
responses:
200:
description: Returns PDF
schema:
type: file
Out of the options you gave, that's the right option. Also, make sure to use produces: [application/pdf]
If it fails for you, make sure you use the latest version of the editor. There was a bug related to the file type that was recently resolved.
With Open API 3.0 ,try below responses:
get:
summary: Returns the report in the PDF format
responses:
'200':
description: A PDF file
content:
application/pdf:
schema:
type: string
format: binary
Documentation: swagger.io/docs/specification/describing-responses
Section: Response That Returns a File