I have a service that creates a multipart file containing:
a data byte array that represents an image buffer
a JSON that represents information about the image (coord, format, etc.)
Is it possible to model this custom response in an OpenAPI (Swagger) definition, using YAML?
Multipart responses can be described using OpenAPI 3.0, but not OpenAPI 2.0 (fka Swagger 2.0).
openapi: 3.0.0
...
paths:
/something:
get:
responses:
'200':
description: OK
content:
multipart/mixed: # <-- Content-Type of the response
schema:
type: object
properties:
# Part 1 - application/octet-stream
file: # <-- part name
type: string
format: binary
# Part 2 - application/json
metadata: # <-- part name
type: object
properties:
foo:
type: string
example: bar
required:
- foo
# Optional, see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#encoding-object
encoding:
file:
...
metadata:
...
The optional encoding key can be used to override the Content-Type for subparts or add headers for subparts (e.g. Content-Disposition).
Related
How to define a list of files in Swagger?
Here is what I did but it doesn't work.
OpenAPI 2.0
In OpenAPI 2.0 (swagger: '2.0'), you have to define each file as a separate parameter. This means you can only describe requests that send a fixed/limited number of files. There is no way to define an unbound array of files.
paths:
/something:
post:
consumes:
- multipart/form-data
parameters:
- in: formData
name: file1
type: file
- in: formData
name: file2
type: file
- ...
OpenAPI 3.0
Arrays of files are supported in OpenAPI 3.0. The request can be defined as follows:
openapi: 3.0.0
paths:
/something:
post:
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
# "reports" will be used as the name of each file part/field
# in the multipart request
reports:
type: array
items:
type: string
format: binary
OpenAPI 3.1
OAS 3.1 also supports file arrays, but the syntax is slightly different from 3.0. Specifically, file arrays use items: {} instead of binary string items.
openapi: 3.1.0
paths:
/something:
post:
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
# "reports" will be used as the name of each file part/field
# in the multipart request
reports:
type: array
items: {}
How do I set a content type other than application/json for a body parameter in Swagger UI 3.x using a Swagger (Open API) 2.0 YAML definition file?
My YAML file is as follows, with the consumes element set to application/json+fhir and application/xml+fhir:
swagger: '2.0'
info:
title: Test
version: '1.0'
host: 'server.com'
basePath: /fhir
schemes:
- http
paths:
/Patient/$getrecordsection:
post:
tags:
- Get record section
summary: Retrieve a care record section
consumes:
- application/json+fhir
- application/xml+fhir
produces:
- application/json+fhir
- application/xml+fhir
parameters:
- in: body
name: body
description: ''
required: true
schema:
$ref: '#/definitions/GetRecordSection'
responses:
'200':
description: OK
'400':
description: Bad request
definitions:
GetRecordSection:
type: object
properties:
resourceType:
type: string
default: "Parameters"
parameter:
type: string
example:
resourceType: "Parameters"
parameter:
- name: "patientIdentifier"
valueIdentifier:
system: "http://fhir.provider.net/Id/patient-identifier"
value: "9999999999"
- name: "recordSection"
valueCodeableConcept:
coding:
- system: "http://fhir.provider.net/ValueSet/record-section"
code: "ALL"
xml:
name: Parameters
However, the Swagger UI only shows application/json as the body parameter content type:
I'm using the current latest Swagger UI build - 3.11.0.
This is a problem with Swagger UI, rather than the Swagger Editor (though I know the two share a significant number of components), and so the root cause could be the same.
This is a bug in the 3.11.0 version of Swagger UI, using Swagger/Open API 2.0:
https://github.com/swagger-api/swagger-ui/issues/4257
I have an image upload endpoint that looks like /test/{id}/relationships/image. I want to describe this endpoint using OpenAPI 2.0 (Swagger 2.0).
The endpoint has both path and formData parameters. I tried the following:
swagger: '2.0'
info:
title: API
version: 1.0.0
host: api.server.de
schemes:
- https
produces:
- application/json
paths:
'/test/{id}/relationships/image':
post:
operationId: addImage
consumes:
- multipart/form-data
parameters:
- in: path
name: id
required: true
schema:
type: integer
format: int32
- in: formData
name: file
type: file
required: true
description: The file to upload.
- in: formData
name: metadata
type: string
required: false
description: Description of file contents.
responses:
'202':
description: Uploaded
But Swagger Editor shows errors:
Schema error at
paths['/test/{id}/relationships/image'].post.parameters[0].in should
be equal to one of the allowed values allowedValues: body, header,
formData, query Jump to line 17
Schema error at
paths['/test/{id}/relationships/image'].post.parameters[0] should NOT
have additional properties additionalProperty: schema, in, name,
required Jump to line 17
What am I doing wrong?
In your path parameter, change
schema:
type: integer
format: int32
to
type: integer
format: int32
In OpenAPI/Swagger 2.0, path, header, query and formData parameters use type directly, without a schema. The schema keyword is used for body parameters only.
I am trying to use Swagger to define an API that accepts an actual file and a schema object that describes the contents of a file. Here is a snippet of the Swagger YAML. However it won't validate in the Swagger Editor.
/document:
post:
summary: Api Summary
description: Api Description
consumes:
- multipart/form-data
parameters:
- name: documentDetails
in: formData
description: Document Details
required: true
schema:
$ref: '#/definitions/Document'
- name: document
in: formData
description: The actual document
required: true
type: file
The Swagger Editor throws the following validation error:
Swagger Error: Data does not match any schemas from 'oneOf'
Am I missing something? Or Is this not a supported feature of Swagger?
This is possible in OpenAPI 3.0, but not in OpenAPI/Swagger 2.0.
OpenAPI/Swagger 2.0 does not support objects in form data. Form parameters can be primitive values, arrays of primitives, and files, but not objects. So your example cannot be described using OpenAPI 2.0.
In OpenAPI 3.0, you can use:
paths:
/document:
post:
summary: Api Summary
description: Api Description
requestBody:
required: true
content:
multipart/form-data:
# Form parameters from 2.0 become body schema properties in 3.0
schema:
type: object
properties:
# Schema properties correspond to individual parts
# of the multipart request
document:
# In 3.0, files are binary strings
type: string
format: binary
description: The actual document
documentDetails:
$ref: '#/components/schemas/Document'
# The default Content-Type for objects is `application/json`
required:
- document
- documentDetails
Relevant parts of the 3.0 Specification:
Considerations for File Uploads
Special Considerations for multipart Content
swagger does not support type 'object' in formData, only as body parameters.
It is not possible using Swagger 2.0 , you can only read it as a type 'file' ,
https://swagger.io/docs/specification/2-0/file-upload/
On a related note please be aware that uploading array of files is also not supported in Swagger 2.0 but it is supported in Open API 3.0 .
https://github.com/OAI/OpenAPI-Specification/issues/254
I'm preparing my API documentation by doing it per hand and not auto generated. There I have headers that should be sent to all APIs and don't know if it is possible to define parameters globally for the whole API or not?
Some of these headers are static and some has to be set when call to API is made, but they are all the same in all APIs, I don't want to copy and paste parameters for each API and each method as this will not be maintainable in the future.
I saw the static headers by API definition but there is no single document for how somebody can set them or use them.
Is this possible at all or not?
It depends on what kind of parameters they are.
The examples below are in YAML (for readability), but you can use http://www.json2yaml.com to convert them to JSON.
Security-related parameters: Authorization header, API keys, etc.
Parameters used for authentication and authorization, such as the Authorization header, API key, pair of API keys, etc. should be defined as security schemes rather than parameters.
In your example, the X-ACCOUNT looks like an API key, so you can use:
swagger: "2.0"
...
securityDefinitions:
accountId:
type: apiKey
in: header
name: X-ACCOUNT
description: All requests must include the `X-ACCOUNT` header containing your account ID.
# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
- accountId: []
or in OpenAPI 3.0:
openapi: 3.0.0
...
components:
securitySchemes:
accountId:
type: apiKey
in: header
name: X-ACCOUNT
description: All requests must include the `X-ACCOUNT` header containing your account ID.
# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
- accountId: []
Tools may handle security schemes parameters differently than generic parameters. For example, Swagger UI won't list API keys among operation parameters; instead, it will display the "Authorize" button where your users can enter their API key.
Generic parameters: offset, limit, resource IDs, etc.
OpenAPI 2.0 and 3.0 do not have a concept of global parameters. There are existing feature requests:
Allow for responses and parameters shared across all endpoints
Group multiple parameter definitions for better maintainability
The most you can do is define these parameters in the global parameters section (in OpenAPI 2.0) or the components/parameters section (in OpenAPI 3.0) and then $ref all parameters explicitly in each operation. The drawback is that you need to duplicate the $refs in each operation.
swagger: "2.0"
...
paths:
/users:
get:
parameters:
- $ref: '#/parameters/offset'
- $ref: '#/parameters/limit'
...
/organizations:
get:
parameters:
- $ref: '#/parameters/offset'
- $ref: '#/parameters/limit'
...
parameters:
offset:
in: query
name: offset
type: integer
minimum: 0
limit:
in: query
name: limit
type: integer
minimum: 1
maximum: 50
To reduce code duplication somewhat, parameters that apply to all operations on a path can be defined on the path level rather than inside operations.
paths:
/foo:
# These parameters apply to both GET and POST
parameters:
- $ref: '#/parameters/some_param'
- $ref: '#/parameters/another_param'
get:
...
post:
...
If you're talking about header parameters sent by consumer when calling the API...
You can at least define them once and for all in parameters sections then only reference them when needed.
In the example below:
CommonPathParameterHeader, ReusableParameterHeader and AnotherReusableParameterHeader are defined once and for all in parameterson the root of the document and can be used in any parameters list
CommonPathParameterHeaderis referenced in parameters section of /resources and /other-resources paths, meaning that ALL operation of these paths need this header
ReusableParameterHeader is referenced in get /resources meaning that it's needed on this operation
Same thing for AnotherReusableParameterHeader in get /other-resources
Example:
swagger: '2.0'
info:
version: 1.0.0
title: Header API
description: A simple API to learn how you can define headers
parameters:
CommonPathParameterHeader:
name: COMMON-PARAMETER-HEADER
type: string
in: header
required: true
ReusableParameterHeader:
name: REUSABLE-PARAMETER-HEADER
type: string
in: header
required: true
AnotherReusableParameterHeader:
name: ANOTHER-REUSABLE-PARAMETER-HEADER
type: string
in: header
required: true
paths:
/resources:
parameters:
- $ref: '#/parameters/CommonPathParameterHeader'
get:
parameters:
- $ref: '#/parameters/ReusableParameterHeader'
responses:
'200':
description: gets some resources
/other-resources:
parameters:
- $ref: '#/parameters/CommonPathParameterHeader'
get:
parameters:
- $ref: '#/parameters/AnotherReusableParameterHeader'
responses:
'200':
description: gets some other resources
post:
responses:
'204':
description: Succesfully created.
If you're talking about header sent with each API response...
Unfortunately you cannot define reusable response headers.
But at least you can define a reusable response containing these headers for common HTTP responses such as a 500 error.
Example:
swagger: '2.0'
info:
version: 1.0.0
title: Header API
description: A simple API to learn how you can define headers
parameters:
CommonPathParameterHeader:
name: COMMON-PARAMETER-HEADER
type: string
in: header
required: true
ReusableParameterHeader:
name: REUSABLE-PARAMETER-HEADER
type: string
in: header
required: true
AnotherReusableParameterHeader:
name: ANOTHER-REUSABLE-PARAMETER-HEADER
type: string
in: header
required: true
paths:
/resources:
parameters:
- $ref: '#/parameters/CommonPathParameterHeader'
get:
parameters:
- $ref: '#/parameters/ReusableParameterHeader'
responses:
'200':
description: gets some resources
headers:
X-Rate-Limit-Remaining:
type: integer
X-Rate-Limit-Reset:
type: string
format: date-time
/other-resources:
parameters:
- $ref: '#/parameters/CommonPathParameterHeader'
get:
parameters:
- $ref: '#/parameters/AnotherReusableParameterHeader'
responses:
'200':
description: gets some other resources
headers:
X-Rate-Limit-Remaining:
type: integer
X-Rate-Limit-Reset:
type: string
format: date-time
post:
responses:
'204':
description: Succesfully created.
headers:
X-Rate-Limit-Remaining:
type: integer
X-Rate-Limit-Reset:
type: string
format: date-time
'500':
$ref: '#/responses/Standard500ErrorResponse'
responses:
Standard500ErrorResponse:
description: An unexpected error occured.
headers:
X-Rate-Limit-Remaining:
type: integer
X-Rate-Limit-Reset:
type: string
format: date-time
About OpenAPI (fka. Swagger) Next version
The OpenAPI spec (fka. Swagger) will evolve and include the definition of reusable response headers among other things (cf. https://github.com/OAI/OpenAPI-Specification/issues/563).
As per this Swagger issue comment, support for global parameters (including header parameters) is not planned in foreseeable future, but to limit the repetition you should use parameters references as in #Arnaud's answer (parameters: - $ref: '#/parameters/paramX').
also wish some global variables, can be used anywhere.
( even in some examples, so can change common settings globally in ui ).
something like
"hello ${var1}" in shell or javascript.
searched docs many times, not found solution yet.
: (