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:
1requestBody:2 content:3 image/png:4 schema:5 type: string6 format: binary
This definition corresponds to an HTTP request that looks as follows:
1POST /upload2Host: example.com3Content-Length: 8084Content-Type: image/png5
6[file content goes there]
Upload via Multipart Requests
To describe a file sent with other data, use the multipart
media type. For example:
1requestBody:2 content:3 multipart/form-data:4 schema:5 type: object6 properties:7 orderId:8 type: integer9 userId:10 type: integer11 fileName:12 type: string13 format: binary
The corresponding HTTP request payload will include multiple parts:
1POST /upload2Host: example.com3Content-Length: 27404Content-Type: multipart/form-data; boundary=abcde123455
6--abcde123457Content-Disposition: form-data; name="orderId"8
9119510--abcde1234511Content-Disposition: form-data; name="userId"12
1354514--abcde1234515Content-Disposition: form-data; name="fileName"; filename="attachment.txt"16Content-Type: text/plain17
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):
1requestBody:2 content:3 multipart/form-data:4 schema:5 type: object6 properties:7 filename:8 type: array9 items:10 type: string11 format: binary
The corresponding HTTP request will look as follows:
1POST /upload2Host: example.com3Content-Length: 27404Content-Type: multipart/form-data; boundary=abcde123455
6--abcde123457Content-Disposition: form-data; name="fileName"; filename="file1.txt"8Content-Type: text/plain9
10[file content goes there]11--abcde1234512Content-Disposition: form-data; name="fileName"; filename="file2.png"13Content-Type: image/png14
15[file content goes there]16------WebKitFormBoundaryWfPNVh4wuWBlyEyQ17Content-Disposition: form-data; name="fileName"; filename="file3.jpg"18Content-Type: image/jpeg19
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