OpenAPIでのファイルアップロードエンドポイント

OpenAPIでのファイルアップロード

ファイルアップロードは通常の application/json の代わりに multipart/form-data エンコーディングを使用するため、OpenAPIで特別な処理が必要です。OpenAPI 3.0は単一ファイル、複数ファイル、ファイルとメタデータの組み合わせをドキュメント化するクリーンな方法を提供します。

単一ファイルアップロード

/upload/avatar:
  post:
    summary: ユーザーアバターのアップロード
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required:
              - file
            properties:
              file:
                type: string
                format: binary
                description: 画像ファイル（JPEG、PNG、WebP）

format: binary はツールにこのフィールドが生のファイルデータを受け入れることを伝えます。

メタデータ付きファイル

JSON風のフォームフィールドと一緒にファイルをアップロード：

/upload/document:
  post:
    summary: メタデータ付きドキュメントのアップロード
    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]
          encoding:
            file:
              contentType: application/pdf, image/*

Base64エンコードファイル

multipartの代替 — JSONにBase64としてファイルを埋め込み：

/upload/inline:
  post:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              filename:
                type: string
              content:
                type: string
                format: byte
                description: Base64エンコードされたファイルコンテンツ

format: byte はBase64エンコードされたバイナリデータを、format: binary は生のバイナリを示します。