OpenAPIのリクエストとレスポンススキーマ

OpenAPIのリクエストとレスポンススキーマ

スキーマはOpenAPI仕様の中核です。APIが受け入れるデータと返すデータの正確な形状を定義し、ドキュメントとクライアント・サーバー間の契約の両方として機能します。

基本的なスキーマ型

OpenAPIは以下のプリミティブ型をサポートします：

# 文字列
name:
  type: string
  minLength: 1
  maxLength: 200

# 整数
age:
  type: integer
  minimum: 0
  maximum: 150

# 数値（浮動小数点）
price:
  type: number
  format: double

# ブール値
active:
  type: boolean

# Enum
status:
  type: string
  enum: [draft, published, archived]

オブジェクトスキーマ

オブジェクトは複数のフィールドとオプションの必須制約を組み合わせます：

User:
  type: object
  required:
    - email
    - name
  properties:
    id:
      type: string
      format: uuid
      readOnly: true
    email:
      type: string
      format: email
    name:
      type: string
    bio:
      type: string
      nullable: true

配列スキーマ

配列は別のスキーマ型をラップします：

Tags:
  type: array
  items:
    type: string
  minItems: 1
  maxItems: 10
  uniqueItems: true

$refによるスキーマの再利用

$ref キーワードは重複を防ぎます：

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

allOf、oneOf、anyOfによる合成

多態性のためにスキーマを組み合わせます：

AdminUser:
  allOf:
    - $ref: "#/components/schemas/User"
    - type: object
      properties:
        permissions:
          type: array
          items:
            type: string

スキーマの継承に allOf、排他的バリアントに oneOf、柔軟な結合に anyOf を使用することで、強力な型合成が可能になります。