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:

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]
------WebKitFormBoundaryWfPNVh4wuWBlyEyQ
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