模型 OpenAPI 2.0 文件下载，类型字符串：二进制与类型文件

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和 https://github.com/OAI/OpenAPI-Specification/blob/master/版本/2.0.md#response-object（响应数据类型file）但我不清楚两者有何不同。应该在什么时候使用？

此外，Content-Disposition标题的使用对选择一个或另一个有影响吗？

自我注意，也看了

• https://github.com/OAI/OpenAPI-Specification/issues/430
• https://github.com/OAI/OpenAPI-Specification/issues/50
• https://github.com/swagger-api/swagger-codegen/issues/319#issuecomment-113880278

Answer 1

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

在 OAS v3 中，file已被替代，type: string, format: binary因此如果您打算最终将规范升级到 OAS v3，我建议您从现在开始使用二进制