REST APIリクエストボディ用のJSON Schema生成

サンプルデータからAPIリクエストスキーマを構築する

JSON Schema生成の最も実用的な用途の一つは、REST APIリクエストボディのバリデーションスキーマの作成です。ゼロからスキーマを書く代わりに、サンプルペイロードを貼り付けて出力を改善します。

サンプルAPIリクエスト

典型的なECサイトの注文作成エンドポイントを考えてみましょう:

{
  "customerId": "cust_abc123",
  "items": [
    {
      "productId": "prod_001",
      "quantity": 2,
      "price": 29.99
    }
  ],
  "shipping": {
    "method": "express",
    "address": {
      "street": "123 Main St",
      "city": "Portland",
      "state": "OR",
      "zip": "97201"
    }
  },
  "couponCode": null
}

生成後の改善ステップ

1. 予期しないフィールドを拒否するために additionalProperties: false を追加。
2. required を確認: couponCode はnullableなのでオプショナルにすべき。
3. 制約を追加: items配列に minItems: 1、priceとquantityに minimum: 0。
4. shipping.method に enum を追加: ["standard", "express", "overnight"]。
5. IDフィールドに pattern を追加して命名規則を強制。

APIフレームワークとの統合

スキーマが準備できたら、以下に直接プラグインできます:

• Express.js: Ajvミドルウェアで受信リクエストボディを検証。
• FastAPI: Pydanticモデルに変換して自動バリデーション。
• OpenAPI/Swagger: API仕様にスキーマを埋め込んでドキュメントとクライアントコード生成。

生成してから改善するワークフローは、特にネストされたオブジェクトと配列を持つ大きなペイロードの場合、手作業でスキーマを書くよりも大幅に高速です。