File Upload

Note

OAS 3 This guide is for OpenAPI 3.0. If you use OpenAPI 2.0, see our OpenAPI 2.0 guide.

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:

requestBody:
  content:
    image/png:
      schema:
        type: string
        format: binary

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

POST /upload
Host: example.com
Content-Length: 808
Content-Type: image/png

[file content goes there]

Upload via Multipart Requests

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

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          orderId:
            type: integer
          userId:
            type: integer
          fileName:
            type: string
            format: binary

The corresponding HTTP request payload will include multiple parts:

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

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

1195
--abcde12345
Content-Disposition: form-data; name="userId"

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

[file content goes there]
--abcde12345--

Multiple File Upload

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

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          filename:
            type: array
            items:
              type: string
              format: binary

The corresponding HTTP request will look as follows:

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

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

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

[file content goes there]
--abcde12345
Content-Disposition: form-data; name="fileName"; filename="file3.jpg"
Content-Type: image/jpeg

[file content goes there]
--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