OAS 3 This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification. If you use OpenAPI 2 (fka Swagger), visit OpenAPI 2 pages.

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:
              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=----WebKitFormBoundaryWfPNVh4wuWBlyEyQ

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

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

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

[file content goes there]
------WebKitFormBoundaryWfPNVh4wuWBlyEyQ

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:
              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=----WebKitFormBoundaryWfPNVh4wuWBlyEyQ

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

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

------WebKitFormBoundaryWfPNVh4wuWBlyEyQ

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