api-designer

API デザイナー

REST、GraphQL、gRPC に対応したコントラクトファーストの API 設計です。OpenAPI 3.1 仕様を作成し、既存 API をレビューし、後方互換性を分析して、クライアントコードのスキャフォールディングを行います。

標準用語

用語	定義
spec	API の公開範囲を記述した OpenAPI 3.1 ドキュメント（YAML または JSON）
endpoint	REST API におけるパスとメソッドの組み合わせ、GraphQL におけるクエリ／ミューテーション、gRPC における RPC
breaking change	コードを変更しないと既存のクライアントが動作しなくなる変更
non-breaking change	後方互換性のある変更（フィールドの追加、新しいエンドポイント、任意パラメーターなど）
resource	API を通じて公開されるドメインエンティティ（REST では名詞ベースの URL セグメント）
contract	spec によって定義された、API の提供者と利用者の正式な合意
protocol	API のパラダイム：REST、GraphQL、または gRPC
surface	API が公開するエンドポイント、型、操作の全体
versioning strategy	URL パス、ヘッダー、またはクエリパラメーターを使って、破壊的変更を通知する方法

ディスパッチ

$ARGUMENTS	アクション
design <requirements>	要件に基づいて新しい API を設計する
spec <code or path>	既存のコードから OpenAPI 3.1 spec を生成する
review <spec or path>	既存の API 設計を監査する
version <spec or path>	バージョニングと非推奨化の戦略
compat <old> <new>	後方互換性の差分を分析する
sdk <spec or path>	クライアントコードの構成をスキャフォールディングする
API 設計に関する自然言語の入力	意図からモードを自動検出する
空	使用例とともにモードメニューを表示する

モードメニュー（引数なし）

#	モード	例
1	設計	design "User management API with RBAC"
2	Spec	spec src/routes/
3	レビュー	review openapi.yaml
4	バージョン	version openapi.yaml
5	互換性	compat v1.yaml v2.yaml
6	SDK	sdk openapi.yaml

番号を選ぶか、必要な内容を説明してください。

プロトコルの検出

いずれかのモードに入る前に、入力から API プロトコルを検出します。分類によって、適用する規約とパターンが決まります。

検出シグナル：

シグナル	REST	GraphQL	gRPC
ファイル拡張子	.yaml、.json（OpenAPI）	.graphql、.gql	.proto
キーワード	endpoint、resource、CRUD、path	query、mutation、subscription、resolver	service、rpc、message、protobuf
URL パターン	/api/v1/resources	/graphql	gRPC サービス名
コードパターン	Express/FastAPI のルート、コントローラー	スキーマ定義、リゾルバー	Proto サービス定義

振り分け：

• いずれかのプロトコルを明確に示すシグナルがある場合：そのプロトコルの規約に従って進めます
• 複数のプロトコルを示すシグナルがある場合、または曖昧な場合：ユーザーに「どのプロトコルですか？［REST / GraphQL / gRPC］」と尋ねます
• プロトコルの文脈がない場合（要件のみ）：REST をデフォルトにし、その前提を明記します

検出したプロトコルに応じて、references/rest-conventions.md、references/graphql-patterns.md、または references/grpc-patterns.md を読み込みます。

モード A：設計

要件から新しい API を設計します。references/rest-conventions.md（またはプロトコル固有のリファレンス）を読み込みます。

設計手順

1. 要件を解析する — リソース、関係、操作、認証要件、制約を抽出します
2. リソースをモデル化する — 属性、関係、カーディナリティを含めてリソースを定義します
3. エンドポイントを設計する — プロトコルの規約に従って、CRUD とカスタム操作をエンドポイントに対応付けます
4. リクエスト／レスポンスのスキーマを定義する — 型、検証ルール、例を含むペイロードを定義します
5. 認証戦略を定める — ユースケースに基づいて、認証方式（API key、OAuth2、JWT）を推奨します
6. エラー契約を定める — コード、メッセージ、詳細オブジェクトを含むエラーレスポンス形式を定義します
7. ページネーションとフィルタリングを定める — カーソルまたはオフセットによるページネーション、フィルターのクエリパターンを適用します
8. レート制限を定める — エンドポイントの機密性と想定負荷に基づいて、制限を推奨します
9. 仕様を生成する — OpenAPI 3.1 の完全な YAML を出力します
10. 検証する — 生成した仕様に対して scripts/api-spec-validator.py を実行します

モード B：Spec

既存のコードから OpenAPI 3.1 を生成します。

Spec の手順

1. コードベースをスキャンする — ルート定義、コントローラー、ハンドラー、デコレーターを読み取ります
2. エンドポイントを抽出する — コードをパス、メソッド、パラメーター、レスポンス型に対応付けます
3. スキーマを推定する — 型注釈または実行時の型からリクエスト／レスポンスのスキーマを構築します
4. 仕様を生成する — 検出したすべてのエンドポイントを含む OpenAPI 3.1 の YAML を出力します
5. 検証する — scripts/api-spec-validator.py を実行します
6. 不足項目を報告する — 説明、例、またはエラーレスポンスがないエンドポイントを一覧表示します

モード C：Review

既存の API 設計を監査します。読み取り専用の分析です。

Review の手順

1. 仕様を解析する — OpenAPI ドキュメントを読み込み、検証します
2. バリデーターを実行する — scripts/api-spec-validator.py で構造上の問題を確認します
3. エンドポイントマトリックスを実行する — scripts/api-endpoint-matrix.py で API の全体像を確認します
4. 規約を確認する — references/rest-conventions.md に照らして、命名、HTTP メソッドの使用方法、ステータスコードを確認します
5. セキュリティを監査する — 認証の適用範囲、HTTPS の強制、機密データの露出を確認します
6. 一貫性を確認する — 命名パターン、レスポンスエンベロープの一貫性、エラー形式の統一性を確認します
7. 報告する — 重要度（critical、warning、info）別に、具体的な修正案を添えて調査結果を提示します

モード D：Version

バージョニングと非推奨化の戦略を定めます。

Version の手順

1. 現状を分析する — 仕様を解析し、バージョンを示す要素を特定します
2. 戦略を推奨する — URL パス、ヘッダー、クエリパラメーターによるバージョニングを比較します（references/versioning-strategies.md を読み込みます）
3. 非推奨化計画を立てる — 非推奨エンドポイントのタイムライン、sunset ヘッダー、移行ガイドを定めます
4. バージョンマトリックスを作成する — 各バージョンに存在するエンドポイントを示す表を作成します
5. 移行ガイドのテンプレートを作成する — 利用者向け移行ドキュメントの骨組みを作成します

モード E：Compat

2 つの仕様バージョン間で後方互換性の差分を確認します。

Compat の手順

1. 両方の仕様を読み込む — 古い OpenAPI ドキュメントと新しい OpenAPI ドキュメントを解析します
2. 互換性チェッカーを実行する — scripts/compat-checker.py <old> <new>
3. 変更を分類する — 変更の種類と箇所を含めて、破壊的変更と非破壊的変更に分類します
4. 影響を評価する — 影響を受ける利用者と、移行に必要な労力を見積もります
5. 修正案を示す — 破壊的変更ごとに、後方互換性を保つ代替案を提示します

モード F：SDK

仕様からクライアントコードの構造をひな形として生成します。公開可能な SDK パッケージではなく、構造の出発点です。

SDK の手順

1. 仕様を解析する — エンドポイント、スキーマ、認証要件を抽出します
2. リソースごとにまとめる — エンドポイントを論理的なクライアントモジュールに整理します
3. クライアントの骨組みを生成する — 型付きパラメーターと戻り値の型を持つメソッドのスタブを作成します
4. 認証を統合する — 認証方式をクライアントのコンストラクターに組み込みます
5. エラー処理を実装する — API エラーコードをクライアントの例外に対応付けます
6. 使用例を作成する — よく使われる操作を示す例をリソースごとに 1 つ作成します

スクリプト

スクリプト	目的	実行するタイミング
scripts/api-spec-validator.py	OpenAPI 3.x の完全性とベストプラクティスへの準拠を検証します	設計、仕様、レビュー
scripts/api-endpoint-matrix.py	仕様からエンドポイント一覧を抽出します	レビュー、バージョン管理、SDK
scripts/compat-checker.py	2 つの仕様を比較して、破壊的変更を確認します	互換性

スクリプトの実行

uv run python skills/api-designer/scripts/api-spec-validator.py <spec-path>
uv run python skills/api-designer/scripts/api-endpoint-matrix.py <spec-path>
uv run python skills/api-designer/scripts/compat-checker.py <old-spec> <new-spec>

すべてのスクリプトは JSON を標準出力に、警告を標準エラー出力に出力します。

参照ファイル一覧

ファイル	内容	読み込むタイミング
references/rest-conventions.md	REST のベストプラクティス、HTTP メソッド、ステータスコード、命名、ページネーション、レート制限	設計、仕様、レビュー（REST）
references/graphql-patterns.md	GraphQL スキーマ設計、クエリパターン、エラー処理、サブスクリプション	設計、仕様、レビュー（GraphQL）
references/grpc-patterns.md	gRPC サービスパターン、proto 設計、ストリーミング、エラーコード	設計、仕様、レビュー（gRPC）
references/versioning-strategies.md	URL、ヘッダー、クエリによるバージョン管理、非推奨化、後方互換性のチェックリスト	バージョン管理、互換性
data/http-conventions.json	HTTP メソッドのセマンティクスに関する参照データ	スクリプト
data/status-codes.json	HTTP ステータスコードガイドの参照データ	スクリプト

参照資料を一度にすべて読み込まないでください。検出されたプロトコルと現在のモードに必要なものだけを読み込んでください。

重要なルール

1. いずれのモードに入る前にも、必ずプロトコルを検出してください。根拠なく REST と決めつけないでください
2. プロトコルが曖昧な場合は、推測せずにユーザーに確認してください
3. 生成した仕様は、ユーザーに提示する前に api-spec-validator.py に合格させてください
4. すべてのエンドポイントに、少なくとも 1 つのエラーレスポンス（4xx または 5xx）を定義してください
5. コレクションを返すリストエンドポイントを、ページネーションなしで設計しないでください
6. 互換性モードで破壊的変更を示す場合は、修正案も提示してください
7. SDK モードでは構造的なスキャフォールドのみを生成してください。出力が本番環境で使用可能だと決して主張しないでください
8. 正式な用語を一貫して使ってください。「swagger」ではなく「spec」、「route」ではなく「endpoint」としてください
9. すべての仕様は OpenAPI 3.1 を対象とします。Swagger 2.0 や OpenAPI 3.0 を生成しないでください
10. MCP サーバーには使用しないでください（mcp-creator を使用してください）。フロントエンドの API クライアントコードも対象外です

対象範囲

対象：

• 要件に基づく新しい REST、GraphQL、または gRPC API の設計
• 既存コードからの OpenAPI 仕様の生成
• API 設計のレビューと監査
• バージョン管理戦略と非推奨化の計画
• 仕様バージョン間の破壊的変更の分析
• クライアントコードの構造のスキャフォールディング

対象外：

• MCP サーバーの API（/mcp-creator を使用）
• フロントエンドの API クライアントの実装
• API ゲートウェイの設定
• 実行時の API テストや負荷テスト
• データベーススキーマの設計（/database-architect を使用）