如何编写OpenAPI 3.0中返回文件的GET请求规范？

场景1：返回单个文件 #

如果你的GET接口只返回单个文件（比如PDF、图片、压缩包等），完全不需要用multipart/form-data，直接指定对应文件的媒体类型即可。通用二进制文件可以用application/octet-stream，特定类型文件用对应的MIME类型（比如application/pdf、image/png等）。

示例写法：

responses:
  '200':
    description: 成功返回文件
    content:
      # 替换为实际返回的文件MIME类型，比如application/pdf、image/jpeg
      application/octet-stream:
        schema:
          type: string
          format: binary
          description: 文件的二进制字节流

如果是特定类型文件（比如PDF），可以更明确地写：

responses:
  '200':
    description: 成功返回PDF文件
    content:
      application/pdf:
        schema:
          type: string
          format: binary
          description: PDF文件的二进制数据

场景2：返回多个文件（使用multipart） #

如果接口需要一次性返回多个文件，才需要用到multipart/form-data，这时候写法和你之前的思路类似，但要注意这属于GET响应的场景（实际业务中这种情况比较少见）。

示例写法：

responses:
  '200':
    description: 成功返回多个文件
    content:
      multipart/form-data:
        schema:
          type: object
          properties:
            file1:
              type: string
              format: binary
              description: 第一个文件的字节流
            file2:
              type: string
              format: binary
              description: 第二个文件的字节流

补充说明 #

你之前的写法确实更常用于POST上传文件的请求体，GET返回单个文件时，直接用对应MIME类型的写法才是规范且符合常规业务场景的。

内容的提问来源于stack exchange，提问作者Ricardo de Vries