OpenAPI: File Upload Multipart Endpoint

Documenting File Uploads in OpenAPI 3.0

File uploads use multipart/form-data content type. OpenAPI 3.0 has specific support for describing binary file fields and their constraints.

Upload Endpoint Definition

paths:
  /files/upload:
    post:
      summary: Upload a file
      tags:
        - Files
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                description:
                  type: string
                  description: Optional file description
                category:
                  type: string
                  enum:
                    - document
                    - image
                    - video
                  description: File category for organization
            encoding:
              file:
                contentType: image/png, image/jpeg, application/pdf
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'
        '400':
          description: Invalid file type or size exceeded
        '413':
          description: File too large

File Info Response Schema

components:
  schemas:
    FileInfo:
      type: object
      properties:
        id:
          type: string
        filename:
          type: string
        size:
          type: integer
          description: File size in bytes
        mimeType:
          type: string
        url:
          type: string
          description: URL to access the uploaded file
        createdAt:
          type: string

Encoding Section

The encoding field in OpenAPI 3.0 lets you specify content type restrictions for individual form fields. This is essential for documenting accepted file formats (e.g., only PNG, JPEG, or PDF).

Multiple File Upload

For batch uploads, use type: array with items: { type: string, format: binary }:

files:
  type: array
  items:
    type: string
    format: binary
  description: Up to 10 files

Size Limits

Document maximum file sizes in the endpoint description or in a custom extension field. OpenAPI does not have a native size limit field, so use the description to communicate limits like "Maximum 10MB per file".