OpenAPI: マルチパートファイルアップロードエンドポイント

OpenAPI 3.0でのファイルアップロードの文書化

ファイルアップロードはmultipart/form-dataコンテンツタイプを使用します。OpenAPI 3.0にはバイナリファイルフィールドとその制約を記述する固有のサポートがあります。

アップロードエンドポイント定義

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

ファイル情報レスポンススキーマ

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

エンコーディングセクション

OpenAPI 3.0のencodingフィールドにより、個々のフォームフィールドのコンテンツタイプ制限を指定できます。受入ファイル形式（例：PNG、JPEG、PDFのみ）の文書化に不可欠です。

複数ファイルアップロード

バッチアップロードにはtype: arrayとitems: { type: string, format: binary }を使用します：

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

サイズ制限

最大ファイルサイズはエンドポイントの説明またはカスタム拡張フィールドに文書化します。OpenAPIにはネイティブなサイズ制限フィールドがないため、「1ファイルあたり最大10MB」などの制限は説明を使って伝えます。