File Upload Endpoints in OpenAPI
Define file upload endpoints in OpenAPI 3.0 using multipart/form-data. Cover single and multiple file uploads, file size limits, accepted MIME types, and mixed file-with-metadata requests.
Detailed Explanation
File Upload in OpenAPI
File uploads require special handling in OpenAPI because they use multipart/form-data encoding instead of the typical application/json. OpenAPI 3.0 provides a clean way to document single files, multiple files, and file-with-metadata combinations.
Single File Upload
/upload/avatar:
post:
summary: Upload user avatar
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: Image file (JPEG, PNG, WebP)
responses:
"200":
description: Upload successful
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
The format: binary tells tools that this field accepts raw file data.
Multiple File Upload
/upload/documents:
post:
summary: Upload multiple documents
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
files:
type: array
items:
type: string
format: binary
maxItems: 10
File with Metadata
Upload a file alongside JSON-like form fields:
/upload/document:
post:
summary: Upload document with metadata
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- file
- title
properties:
file:
type: string
format: binary
title:
type: string
maxLength: 200
category:
type: string
enum: [report, invoice, contract]
tags:
type: array
items:
type: string
encoding:
file:
contentType: application/pdf, image/*
Content Type Restrictions
Use the encoding section to specify accepted file types:
encoding:
avatar:
contentType: image/jpeg, image/png, image/webp
document:
contentType: application/pdf
Base64 Encoded Files
Alternative to multipart — embed files as Base64 in JSON:
/upload/inline:
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
filename:
type: string
content:
type: string
format: byte
description: Base64-encoded file content
content_type:
type: string
The format: byte indicates Base64-encoded binary data, while format: binary indicates raw binary.
Response with File
Endpoints that return files:
/export/report:
get:
responses:
"200":
description: PDF report
content:
application/pdf:
schema:
type: string
format: binary
Use Case
File upload documentation is essential for APIs that handle avatars, documents, images, or any binary data. Mobile apps uploading photos, web dashboards importing CSV files, and document management systems all need clear multipart upload definitions. The encoding section in OpenAPI ensures tools display correct file type restrictions in interactive documentation.