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

• 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

Telespectroscope

Answer 1

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

Telespectroscope

Answer 2

The type: file was removed in version 3.0.0 of the spec and should be replaced with something like

   schema:
     type: string
     format: binary

In version 3.1.0 it looks like this is the default behavior for content transferred in binary, so the above may even be omitted.

Fancier