openapi - 如何在 OpenAPI YAML 中为 MP3 文件编写响应？

Question

我正在编写一个返回 MP3 文件的 API YAML。我不熟悉多媒体响应。在通过 Google 时，我发现我可以使用 audio/mp3 内容类型。但我找不到任何例子来说明如何去做。我应该如何处理这种音频内容类型？

Answer 1

OpenAPI 3.1

二进制文件响应仅使用媒体类型定义，没有schema:

openapi: 3.1.0
...

paths:
  /something:
    get:
      responses:
        '200':
          description: An audio file
          content:
            audio/mp3: {}

OpenAPI 3.0

文件被定义为二进制字符串(type: string + format: binary):

openapi: 3.0.3
...

paths:
  /something:
    get:
      responses:
        '200':
          description: An audio file
          content:
            audio/mp3:
              schema:
                type: string
                format: binary

OpenAPI 2.0

二进制文件响应是用 type: file 模式定义的。确保还在操作的 produces 列表中指定媒体类型:

swagger: '2.0'
...

paths:
  /something:
    get:
      produces:
        - audio/mp3
      responses:
        200:
          description: An audio file
          schema:
            type: file