如何使用 OpenAPI (Swagger) 描述多部分响应? [英] How to describe a multipart response using OpenAPI (Swagger)?

问题描述

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

I have a service that creates a multipart file containing:

• 表示图像缓冲区的数据字节数组
• 表示图像信息(坐标、格式等)的 JSON

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

Is it possible to model this custom response in an OpenAPI (Swagger) definition, using YAML?

推荐答案

可以使用 OpenAPI 3.0 描述多部分响应，但不能使用 OpenAPI 2.0 (fka Swagger 2.0).

Multipart responses can be described using OpenAPI 3.0, but not 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:
                  ... 

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

The optional encoding key can be used to override the Content-Type for subparts or add headers for subparts (e.g. Content-Disposition).

这篇关于如何使用 OpenAPI (Swagger) 描述多部分响应?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！