OpenAPIのネストされたオブジェクトと配列スキーマ

OpenAPIのネストされたスキーマ

現実のAPIがフラットなデータ構造を扱うことはめったにありません。注文にはラインアイテムが含まれ、ユーザーには住所があり、設定にはネストされた設定項目があります。OpenAPIは複雑なネストされたスキーマを定義するためのいくつかのメカニズムを提供します。

ネストされたオブジェクト

components:
  schemas:
    UserProfile:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        address:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            country:
              type: string

allOfによるスキーマ合成

ベーススキーマを拡張：

BaseEntity:
  type: object
  properties:
    id:
      type: string
      format: uuid
    created_at:
      type: string
      format: date-time

User:
  allOf:
    - $ref: "#/components/schemas/BaseEntity"
    - type: object
      required: [email]
      properties:
        email:
          type: string
          format: email

oneOfとdiscriminatorによる多態性

Notification:
  oneOf:
    - $ref: "#/components/schemas/EmailNotification"
    - $ref: "#/components/schemas/SmsNotification"
  discriminator:
    propertyName: type

ベストプラクティス

• よく使用されるサブオブジェクトを名前付きスキーマに抽出する
• プロパティのコピペではなく allOf を使用して継承する
• 型安全な多態性のために oneOf と discriminator を使用する
• 可読性のためにネストの深さを3-4レベルに制限する