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

Question

I'm a little confused how to model a file download with Swagger/OpenAPI v2. Take this small example:

/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"`

What do I use as response type? Is it type: string & format: binary or simply type: file?

I was looking at 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 (response data type file) but it isn't clear to me how the two are different. Which should be used when?

Also, does the use of the Content-Disposition header make a difference for choosing one or the other?

Note to self, also looked at

Marcel Stör Marcel Stör · Accepted Answer · 2018-10-03T09:36:23

In a private conversation with the OpenAPI folks on gitter.im I was told the following.

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

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

1 Answers