File Upload

In OpenAPI 3.0, you can describe files uploaded directly with the request content and files uploaded with multipart requests. Use the requestBody keyword to describe the request payload containing a file. Under content, specify the request media type (such as image/png or application/octet-stream). Files use a type: string schema with format: binary or format: base64, depending on how the file contents will be encoded. For example:

1
requestBody:
2
  content:
3
    image/png:
4
      schema:
5
        type: string
6
        format: binary

This definition corresponds to an HTTP request that looks as follows:

1
POST /upload
2
Host: example.com
3
Content-Length: 808
4
Content-Type: image/png
5

6
[file content goes there]

Upload via Multipart Requests

To describe a file sent with other data, use the multipart media type. For example:

1
requestBody:
2
  content:
3
    multipart/form-data:
4
      schema:
5
        type: object
6
        properties:
7
          orderId:
8
            type: integer
9
          userId:
10
            type: integer
11
          fileName:
12
            type: string
13
            format: binary

The corresponding HTTP request payload will include multiple parts:

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

6
--abcde12345
7
Content-Disposition: form-data; name="orderId"
8

9
1195
10
--abcde12345
11
Content-Disposition: form-data; name="userId"
12

13
545
14
--abcde12345
15
Content-Disposition: form-data; name="fileName"; filename="attachment.txt"
16
Content-Type: text/plain
17

18
[file content goes there]
19
--abcde12345--

Multiple File Upload

Use the multipart media type to define uploading an arbitrary number of files (an array of files):

1
requestBody:
2
  content:
3
    multipart/form-data:
4
      schema:
5
        type: object
6
        properties:
7
          filename:
8
            type: array
9
            items:
10
              type: string
11
              format: binary

The corresponding HTTP request will look as follows:

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

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

10
[file content goes there]
11
--abcde12345
12
Content-Disposition: form-data; name="fileName"; filename="file2.png"
13
Content-Type: image/png
14

15
[file content goes there]
16
------WebKitFormBoundaryWfPNVh4wuWBlyEyQ
17
Content-Disposition: form-data; name="fileName"; filename="file3.jpg"
18
Content-Type: image/jpeg
19

20
[file content goes there]
21
--abcde12345--

References

For more information about file upload in OpenAPI, see the following sections of the OpenAPI 3.0 Specification:

Considerations for File Uploads

Special Considerations for multipart Content

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