OpenAPI仕様用のYAML Schemaを生成する

JSONからOpenAPI互換のYAML Schemaへ

OpenAPI（旧Swagger）はJSON Schemaのサブセットを使用してリクエストとレスポンスモデルを定義します。JSON APIペイロードをYAML Schemaに変換すると、OpenAPI仕様に直接プラグインできる定義が生成されます。

JSONのAPIレスポンス例

{
  "id": 42,
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "role": "admin",
  "createdAt": "2024-01-15T09:30:00Z",
  "profile": {
    "avatar": "https://cdn.example.com/alice.jpg",
    "bio": "Full-stack developer"
  }
}

OpenAPI互換のYAML Schema

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        name:
          type: string
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, editor, viewer]
        createdAt:
          type: string
          format: date-time
          readOnly: true
        profile:
          $ref: "#/components/schemas/UserProfile"
      required:
        - id
        - name
        - email
        - role

    UserProfile:
      type: object
      properties:
        avatar:
          type: string
          format: uri
          nullable: true
        bio:
          type: string
          maxLength: 500

OpenAPI固有のキーワード

キーワード	目的
readOnly	レスポンスのみに表示
writeOnly	リクエストのみに表示（例：パスワード）
nullable	nullを許可（OpenAPI 3.0スタイル）
format	拡張フォーマット：int32、int64、float、double
example	ドキュメント用のサンプル値
deprecated	フィールドを非推奨としてマーク

再利用のための$ref

components:
  schemas:
    UserList:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
        pagination:
          $ref: "#/components/schemas/Pagination"

    Pagination:
      type: object
      properties:
        page:
          type: integer
        perPage:
          type: integer
        total:
          type: integer

discriminatorによる多態性

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

リクエスト vs レスポンスモデル

入力（作成/更新）と出力（レスポンス）で別々のスキーマを作成します：

UserCreate:
  type: object
  properties:
    name:
      type: string
    email:
      type: string
      format: email
    password:
      type: string
      writeOnly: true
      minLength: 8
  required:
    - name
    - email
    - password

UserResponse:
  allOf:
    - $ref: "#/components/schemas/UserCreate"
    - type: object
      properties:
        id:
          type: integer
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true