api-designer

name	api-designer
description	REST API の設計・OpenAPI 仕様生成・既存仕様レビューを支援する。「APIを設計して」「OpenAPIを作って」「REST APIのエンドポイントを決めて」「ドメインモデルからAPIを設計して」「既存のOpenAPI仕様を見直して」「実装コードからOpenAPIを生成して」「APIのバージョニング戦略を決めて」などで必ず使う。
metadata	{"version":"2.1.0","tier":"stable","category":"design","tags":["api","openapi","rest"]}

API Designer

REST API の設計から OpenAPI スキーマ生成まで一貫して支援するスキル。 ドメインモデル・既存 OpenAPI 仕様・実装コードを入力として受け取り、それぞれの制約に応じた最適なインターフェースを決定する。

前後の工程

• 前工程: ドメインモデル設計、既存 API 仕様・実装コードの収集
• 後工程（フロントエンド）: 生成した OpenAPI スキーマをフロントエンド I/F 設計のインプットとして渡す
• 後工程（DB）: エンドポイント設計と DB アクセスパターンを整合させる

---

実行ルール（必須）

• 各 Step は 入力確認 → 実施 → 出力 の順で進める
• Step 1 の入力収集はユーザーと対話しながら行う
• Step 2 の制約分析は入力の種類によって判断基準が異なる。必ずテンプレートに従い明示する
• 互換性ポリシー（breaking / non-breaking / deprecation）は Step 3 と Step 6 の両方で確認する
• REST 原則への違反は入力・設計・レビューのあらゆる段階で検出し、必ずユーザーに警告する（既存インターフェースでも例外なし）
• Step 6 のセキュリティ最小チェックと OpenAPI ドキュメント品質チェックは省略しない

---

API 設計フロー

Step 1: 入力収集とインプット確認

以下の入力をユーザーと対話しながら確認・収集する。複数受け付けてよい。

確認する入力（優先順位順）

1. openapi_spec — 既存の OpenAPI 仕様ファイル（YAML/JSON）
2. implementation_code — 既存の実装コード（ルーティング定義、コントローラ等）
3. domain_model — ドメインモデル（Mermaid classDiagram 等）
4. api_description — 上記がない場合のフォールバック（API の目的・概要）

入力が揃ったら追加確認（「未定」で可）:

1. API の利用者（SPA / モバイル / サードパーティ / 社内システム）
2. 認証・認可方式（JWT / OAuth2 / API Key / Session など）
3. バージョニング方針（新規 / 既存バージョン継続 / メジャー更新）
4. PII・機微情報の有無（氏名、メール、決済情報など）
5. レートリミット・SLA 要件（あれば）