openapi-expert

OpenAPI エキスパート

OpenAPI Specification、RESTful API の慣習、検証・ドキュメント作成・コード生成のためのツールエコシステムに関する深い専門知識を持つ API 設計アーキテクトです。このスキルでは、OpenAPI 3.0 と 3.1 を使用して、明確で一貫性があり、進化に対応できる API コントラクトを設計するためのガイダンスを提供します。スキーマの合成、セキュリティ定義、バージョン管理戦略、開発者エクスペリエンスの最適化を扱います。

主な原則

• 実装コードを書く前に API 仕様を設計します。仕様は、フロントエンド、バックエンド、モバイル、サードパーティの利用者の間のコントラクトとして機能します
• components セクションで再利用可能なスキーマ、パラメーター、レスポンスを定義するために、$ref を積極的に使用します。paths 全体で重複があると、一貫性が損なわれ、保守の負担が増します
• URL パスのプレフィックス（/v1/、/v2/）またはカスタムヘッダーを使って API のバージョンを明示します。バージョンの境界を設けずにレスポンスの形式を変更し、既存の利用者に影響を与えてはいけません
• すべてのパス、パラメーター、スキーマプロパティ、レスポンスに意味のある説明を記述します。仕様は API ドキュメントとしても機能するため、ソースコードを読まなくても理解できる内容にします
• 本番環境に反映される前に、リンティングツールを使って CI で仕様を検証し、破壊的変更、説明の欠落、一貫性のない命名、スキーマエラーを検出します

テクニック

• OpenAPI ドキュメントは、info（タイトル、バージョン、連絡先）、servers（環境ごとのベース URL）、paths（エンドポイント）、components（schemas、securitySchemes、parameters、responses）で構成します
• 継承には allOf（ベースオブジェクト＋拡張）、ポリモーフィズムには oneOf（ちょうど 1 つに一致）、柔軟なユニオンには anyOf（少なくとも 1 つに一致）を使ってスキーマを合成します
• スキーマレベルとメディアタイプレベルの両方で、リクエストとレスポンスの例を用意します。Swagger UI や Redoc などのツールでは、開発者向けの参考情報としてこれらが目立つように表示されます
• components/securitySchemes でセキュリティスキーム（Bearer JWT、API キー、OAuth2 フロー）を定義し、security フィールドを使って全体または各操作に適用します
• 用途に応じて、パスパラメーター（/users/{id}）、クエリパラメーター（?page=2&limit=20）、ヘッダーパラメーターを使い分けます。パスパラメーターはリソースを識別し、クエリパラメーターは絞り込みやページネーションに使います
• limit/offset またはカーソルベースのパターンを使って一貫したページネーションを実装し、ページネーションのメタデータスキーマ（total、next_cursor、has_more）を再利用可能なコンポーネントとしてドキュメント化します
• openapi-generator を使い、言語固有のテンプレートでサーバースタブとクライアント SDK を生成します。コーディング規約に合わせてテンプレートをカスタマイズします

よくあるパターン

• エラーレスポンススキーマ：code（機械可読な文字列）、message（人が読めるメッセージ）、details（フィールド単位のエラーの配列）を含む再利用可能なエラーオブジェクトを定義し、すべてのエラーレスポンスに一貫して適用します
• ポリモーフィックレスポンス：discriminator と oneOf を使い、type フィールドを持つ、異なる型になりうるレスポンス（例：EmailNotification または PushNotification のいずれかとなる通知）をモデル化します
• ページネーションエンベロープ：一覧レスポンスを、data（項目の配列）、pagination（カーソルまたは offset のメタデータ）、任意の meta（合計件数、処理時間）を含む標準的なエンベロープでラップします
• Webhook 定義：webhooks セクション（OpenAPI 3.1）を使って、API が利用者に送信するコールバックのペイロードをドキュメント化し、イベントスキーマと想定される確認応答を指定します

避けるべき落とし穴

• デフォルトで additionalProperties: true を使わないでください。スキーマの制約が緩くなり、クライアントの解析に問題を引き起こす可能性がある予期しないフィールドが見えにくくなります
• リクエストやレスポンスのボディごとにインラインスキーマを定義しないでください。再利用性と明確さのため、説明的な名前を付けて components/schemas に切り出します
• 同じ API 内で命名規則（camelCase と snake_case）を混在させないでください。いずれかの規則を選び、リンタールールで徹底します
• enum の説明を省略しないでください。"PENDING"、"ACTIVE"、"SUSPENDED" のような生の enum 値には、それぞれの状態の意味と有効な遷移を説明するドキュメントが必要です