swagger - 如何使用 OpenAPI (Swagger) 描述多部分响应？

Question

我有一个服务，它创建一个包含以下内容的多部分文件:

表示图像缓冲区的数据字节数组

表示图像信息(坐标、格式等)的 JSON

是否可以使用 YAML 在 OpenAPI (Swagger) 定义中对此自定义响应进行建模？

Answer 1

可以使用 OpenAPI 3.0 描述多部分响应，但不能使用 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:
                  ... 

可选 encoding 键可用于覆盖 Content-Type子部分或为子部分添加标题(例如 Content-Disposition )。