What I'd like to do is specify that sometimes the response to an API call might be a PDF document, and sometimes it will be JSON. I'd like to do this in OpenAPI 3.0 format. In the case of a PDF, the response would look like this:
responses:
'200':
description: An invoice in PDF format.
content:
application/pdf:
schema:
type: string
format: binary
And in the case of a JSON response, this would describe the response:
responses:
'200':
description: A JSON object containing user name and avatar
content:
application/json:
schema:
$ref: "#/components/schemas/Invoice"
The OAS3 documentation (https://swagger.io/docs/specification/describing-responses/) provides the following example for how to specify that one of a few different JSON schemas could be the response to a particular API call. This is almost what I want, except instead of describing different possible JSON schemas, I'd like to specify different possible content types, as described above. Is there a way to do this in OAS3 format?
responses:
'200':
description: A JSON object containing pet information
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Hamster'
OpenAPI 3 is the successor of the widely used OpenAPI/Swagger 2.0 format, for machine-readable API definitions. It contains a variety of changes, and even though everything that can be expressed in Version 2 is supported in Version 3 as well, specifications are not backwards-compatible.
Format. An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
Just found that this works:
responses:
'200':
description: "An invoice."
content:
application/json:
schema:
$ref: "#/components/schemas/Invoice"
application/pdf:
schema:
type: "string"
format: "binary"
See the "Response Media Types" section here: https://swagger.io/docs/specification/describing-responses/
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With