Question

我想要做的是指定有时对API调用的响应可能是PDF文档，有时它将是JSON。我想以OpenAPI 3.0格式执行此操作。对于PDF，响应将如下所示：

      responses:
        '200':
          description: An invoice in PDF format.
          content:
            application/pdf:
              schema:
                type: string
                format: binary

在JSON响应的情况下，这将描述响应：

      responses:
        '200':
          description: A JSON object containing user name and avatar
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"

OAS3文档（https://swagger.io/docs/specification/describing-responses/）提供了以下示例，说明如何指定几个不同的JSON模式之一可能是对特定API调用的响应。这几乎是我想要的，除了不是描述不同的可能JSON模式，我想指定不同的可能内容类型，如上所述。有没有办法以OAS3格式执行此操作？

      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'

Answer 1

刚发现这有效：

responses:
    '200':
      description: "An invoice."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Invoice"
        application/pdf:
          schema:
            type: "string"
            format: "binary"

请参阅此处的“响应媒体类型”部分：https://swagger.io/docs/specification/describing-responses/

有没有办法在OpenAPI 3.0中描述两种不同的响应类型？

1 个答案: