Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Is there a way to describe two different response types in OpenAPI 3.0?

Tags:

openapi

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'
like image 273
STN Avatar asked May 17 '18 17:05

STN


People also ask

Is OpenAPI 3.0 backwards compatibility?

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.

What are the formats supported by OpenAPI Swagger for their definitions?

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.


1 Answers

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/

like image 107
STN Avatar answered Oct 29 '22 14:10

STN