模型 OpenAPI 2.0 文件下载，类型 string:binary 与类型文件

Question

我对如何使用 Swagger/OpenAPI v2 建模文件下载有点困惑。举这个小例子：

/files/{name}.zip:
  get:
    summary: Returns the requested ZIP file as "file download" i.e. with content-disposition = attachment
    produces:
      - application/zip
    parameters:
      - name: name
        in: path
        required: true
        type: string
    responses:
      200:
        description: OK
        schema:
          type: file      # <- what is it?
        headers:
          Content-Disposition:
            type: string
            description: the value is `attachment; filename="name.zip"`

我使用什么作为响应类型？是 type: string & format: binary 还是 type: file?

我正在查看 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types and https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#response-object（响应数据类型 file），但我不清楚两者有何不同。什么时候应该用哪个？

此外，Content-Disposition header 的使用对选择其中之一有影响吗？

自我说明，也看过

Answer 1

在 gitter.im 上与 OpenAPI 人员的私人对话中，有人告诉我以下内容。

In OAS v3, file has been replaced by type: string, format: binary instead so if you're planning to upgrade your spec to OAS v3 eventually, i would suggest you use binary from now on

Answer 2

规范的 type: file was removed in version 3.0.0 应替换为类似

的内容

   schema:
     type: string
     format: binary

在 3.1.0 版本中它看起来像是 default behavior for content transferred in binary，所以上面甚至可以省略。

模型 OpenAPI 2.0 文件下载，类型 string:binary 与类型文件

Model OpenAPI 2.0 file download, type string:binary vs. type file

swagger

swagger-2.0

openapi