File Upload

Swagger 2.0 supports file uploads sent with Content-Type: multipart/form-data. That is, your API server must consume multipart/form-data for this operation:

1
consumes:
2
  - multipart/form-data

The operation payload is defined using formData parameters (not body parameters). The file parameter must have type: file:

1
paths:
2
  /upload:
3
    post:
4
      summary: Uploads a file.
5
      consumes:
6
        - multipart/form-data
7
      parameters:
8
        - in: formData
9
          name: upfile
10
          type: file
11
          description: The file to upload.

This definition corresponds to the following HTTP request:

1
POST /upload
2
Host: example.com
3
Content-Type: multipart/form-data; boundary=abcde12345
4
Content-Length: 204
5

6
--abcde12345
7
Content-Disposition: form-data; name="upfile"; filename="example.txt"
8
Content-Type: text/plain
9

10
File contents go here.
11
--abcde12345--

Swagger UI displays file parameters using a file input control, allowing the users to browse for a local file to upload.

Upload a File + Other Data

File parameters can be sent along with other form data:

1
parameters:
2
  - in: formData
3
    name: upfile
4
    type: file
5
    required: true
6
    description: The file to upload.
7
  - in: formData
8
    name: note
9
    type: string
10
    required: false
11
    description: Description of file contents.

The corresponding HTTP request payload will include multiple parts:

1
POST /upload
2
Host: example.com
3
Content-Type: multipart/form-data; boundary=abcde12345
4
Content-Length: 332
5

6
--abcde12345
7
Content-Disposition: form-data; name="upfile"; filename="example.txt"
8
Content-Type: text/plain
9

10
File contents go here.
11
--abcde12345
12
Content-Disposition: form-data; name="note"
13

14
Uploading a file named "example.txt"
15
--abcde12345--

Multiple Upload

You can have several named file parameters, each defined individually:

1
parameters:
2
  - in: formData
3
    name: upfile1
4
    type: file
5
    required: true
6
  - in: formData
7
    name: upfile2
8
    type: file
9
    required: false
10
  - in: formData
11
    name: upfile3
12
    type: file
13
    required: false

However, uploading an arbitrary number of files (an array of files) is not supported. There is an open feature request at https://github.com/OAI/OpenAPI-Specification/issues/254. For now, you can use a binary string array as a workaround for uploading an arbitrary number of files:

1
type: array
2
items:
3
  type: string
4
  format: binary

Note that this will not produce the file upload interface in Swagger UI.

FAQ

Can I upload files via PUT?

Swagger 2.0 supports file upload requests with Content-Type: multipart/form-data, but does not care about the HTTP method. You can use POST, PUT or any other method, provided that the operation consumes multipart/form-data. Uploads where the payload is just the raw file contents are not supported in Swagger 2.0, because they are not multipart/form-data. That is, Swagger 2.0 does NOT support something like:

1
curl --upload-file archive.zip http://example.com/upload

Note also that file uploading in Swagger UI only works for POST requests, because HTML forms in browsers support GET and POST methods only.

Can I define the Content-Type for uploaded files?

This is supported in OpenAPI 3.0, but not in OpenAPI/Swagger 2.0. In 2.0, you can say that an operation accepts a file, but you cannot say that this file is of a specific type or structure.

As a workaround, vendor extensions may be used to extend this functionality, for example:

1
- in: formData
2
  name: zipfile
3
  type: file
4
  description: Contents of the ZIP file.
5
  x-mimetype: application/zip

Did not find what you were looking for? Ask the community
Found a mistake? Let us know