Multipart File Upload

Document endpoints with the multipart/form-data content type

Multipart requests combine one or more sets of data into a single body, separated by boundaries. You typically use these requests for file uploads and for transferring data of several types in a single request (for example, a file along with a JSON object).

openapi.yml
1paths:
2  /upload:
3    post:
4      summary: Upload a file
5      description: Upload a file using multipart/form-data encoding
6      operationId: uploadFile
7      tags:
8        - file
9      requestBody:
10        required: true
11        content:
12          multipart/form-data:
13            schema:
14              type: object
15              properties:
16                file:
17                  type: string
18                  format: binary
19                  description: The file to upload
20                description:
21                  type: string
22                  description: A description of the file (optional)
23              required:
24                - file
25      responses:
26        "200":
27          description: Successful upload
28          content:
29            application/json:
30              schema:
31                type: object
32                properties:
33                  message:
34                    type: string
35                  fileId:
36                    type: string

Any request body that is defined with a multipart/form-data content type, will be treated as a multipart request. Within a given multipart request, a string parameter with format:binary will represent an arbitrary file.

Array of Files

If your endpoint supports an array of files, then your request body must use an array type.

1paths:
2  /upload:
3    post:
4      summary: Upload multiple files
5      operationId: uploadFiles
6      requestBody:
7        content:
8          multipart/form-data:
9            schema:
10              type: object
11              properties:
12                files:
13                  type: array
14                  items:
15                    type: string
16                    format: binary
17                  description: An array of files to upload