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

问题

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'

回答1:

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/

来源：https://stackoverflow.com/questions/50397427/is-there-a-way-to-describe-two-different-response-types-in-openapi-3-0

标签

openapi