swagger - 模型 OpenAPI 2.0 文件下载，类型字符串 :binary vs. 类型文件

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/versions/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 人员的私有(private)对话中，我被告知以下内容。

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