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
Related
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.
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'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
Using swagger-editor and swagger-ui to build a swagger2.0 specification in YAML.
I have split the spec into a client.yml and several model.yml files.
Each model defines some parameters or response objects.
When I open client.yml in the editor, it will load the models into the client using $ref:
However, there appears to be a problem if an object in one of the model files tries to reference an object in another model file.
I have tried absolute and relative paths to no avail. I always get an error, like:
"Reference could not be resolved: /models/basemodel.yml#/BasicObject"
path: Array [10]
error: "Cannot use 'in' operator to search for 'BasicObject' in undefined"
level: 900
type: "Swagger Error"
description: "Reference could not be resolved: /models/basemodel.yml#/BasicObject"
lineNumber: -1
The SimplerObject is identical and works fine. This references a CopyOfBasicObject in the same file. The AdvancedObject tries to reference the BasicObject in a different model file.
The goal is to not copy the definition of BasicObject but refer to it.
It is often necessary to clear the browser cache and reload the page before the editor read the new version of the model file.
The files I used to test this are included. I have converted to a single file as stackoverflow editor is not rendering the yaml very well.
swagger: '2.0'
info:
title: test indirect reference
description: etc
version: "Draft 0.1.1"
host: example.com
basePath: /
produces:
- application/json
paths:
/advancedObjects:
post:
summary: |
post an object.
parameters:
- name: advancedObject
in: body
required: true
schema:
type: array
items:
$ref: '/models/model.yml#/AdvancedObject' # This doeesn't work
#$ref: '/models/model.yml#/SimplerObject' # This works fine
#$ref: '/models/basemodel.yml#/BasicObject' # This works fine
responses:
200:
description: OK
definitions:
AdvancedObject: #move to /models/model.yml
type: object
description: Contains a reference to a basic object
properties:
base:
$ref: '/models/basemodel.yml#/BasicObject'
advanced:
type: array
items:
type: number
CopyOfBasicObject: # move to /models/model.yml
type: object
description: Another simple object
properties:
id:
type: number
SimplerObject: # move to /models/model.yml
type: object
description: Same as AdvanceObject but without reference to another file
properties:
base:
$ref: '#/CopyOfBasicObject'
advanced:
type: array
items:
type: number
BasicObject: # move to /models/basemodel.yml
type: object
description: A simple object
properties:
id:
type: number
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