ynitto 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: 入力収集とインプット確認
以下の入力をユーザーと対話しながら確認・収集する。複数受け付けてよい。
確認する入力（優先順位順）
- openapi_spec — 既存の OpenAPI 仕様ファイル（YAML/JSON）
- implementation_code — 既存の実装コード（ルーティング定義、コントローラ等）
- domain_model — ドメインモデル（Mermaid classDiagram 等）
- api_description — 上記がない場合のフォールバック（API の目的・概要）
入力が揃ったら追加確認（「未定」で可）:
1. API の利用者（SPA / モバイル / サードパーティ / 社内システム）
2. 認証・認可方式（JWT / OAuth2 / API Key / Session など）
3. バージョニング方針（新規 / 既存バージョン継続 / メジャー更新）
4. PII・機微情報の有無（氏名、メール、決済情報など）
5. レートリミット・SLA 要件（あれば）
Step 1 の出力: 収集した入力サマリー（種類・内容・有無）
Step 2: 入力分析と制約判断
入力種別ごとの制約ルール
| 入力種別 | インターフェース制約 | 品質チェック |
|---|---|---|
| openapi_spec | 原則変更不可（パス・メソッド・構造を維持。追加は可。削除・変更は breaking change としてユーザー承認を得る） | 必須（境界条件・エラーポリシー・矛盾・曖昧さ・REST 原則をチェックしてフィードバック） |
| implementation_code | コスト考慮（変更量が大きい場合はユーザーに確認） | 必須（openapi_spec との矛盾・未定義エラー・境界条件の漏れをチェック） |
| domain_model | 自由設計（RESTful インターフェースへ具体化。命名・構造はドメイン用語に従う） | — |
| api_description のみ | 自由設計（ベストプラクティスに従い新規設計） | — |
インターフェース制約と品質チェックは独立して扱う。openapi_spec の構造は変えないが、品質上の問題はフィードバックして修正を促す。
複合入力時の優先順位: openapi_spec > implementation_code > domain_model > api_description
openapi_spec の品質チェック項目（必須）
境界条件: パスパラメータの形式制約・クエリパラメータの範囲・リクエストボディの制約・ページネーション上限
エラーポリシー: 各 operation の 4xx/5xx の網羅性・operation 間のステータスコード一貫性・エラースキーマ統一・401/403 の使い分け
矛盾: パスパラメータの定義一致・required フィールドと example の整合・security 上書き漏れ・$ref 参照切れ
曖昧さ: description 省略・operation 間のフィールド名揺れ・nullable/optional の一貫性
REST 原則: パスの動詞使用・リソース複数形・メソッドの意味論的正確性・ステータスコード慣習・ネスト深さ （→ 詳細チェック項目と警告フォーマット: references/rest-design-guide.md）
implementation_code との照合（openapi_spec + implementation_code が両方ある場合）
- 実装に存在するエンドポイントが openapi_spec に定義されているか（未文書エンドポイントの検出）
- 実装が返すエラーコード・ステータスが openapi_spec の responses と一致しているか
- 実装のバリデーションロジックと openapi_spec のスキーマ制約が一致しているか
- 実装の認証・認可の分岐が openapi_spec の security 定義に反映されているか
フィードバックテンプレート（必須）
## OpenAPI 品質チェック結果
### 境界条件の欠落
| 対象 | 問題 | 推奨対応 |
|------|------|---------|
### エラーポリシーの問題
| 対象 | 問題 | 推奨対応 |
|------|------|---------|
### 矛盾
| 対象 | 問題 | 推奨対応 |
|------|------|---------|
### 曖昧さ・REST 原則違反
| 対象 | 問題 | 推奨対応 |
|------|------|---------|
上記の問題を修正してから OpenAPI を生成します。修正不要なものがあれば教えてください。
制約分析テンプレート（必須）
## 制約分析サマリー
- openapi_spec: あり / なし → [あり: 既存パス一覧 + 品質チェック結果]
- implementation_code: あり / なし → [あり: 変更コスト見積もり + 照合チェック結果]
- domain_model: あり / なし → [あり: RESTful 具体化の方針]
## 変更制約マップ
| 対象 | 変更可否 | 備考 |
|------|---------|------|
| （パス / スキーマ / 操作ごとに記載）| 維持 / 追加可 / 要承認 | |
## 設計方針サマリー
- 固定するインターフェース:
- 新規追加するインターフェース:
- 変更提案（ユーザー承認が必要なもの）:
- 品質改善（ユーザー確認後に反映）:
Step 2 の出力: 制約分析サマリー + OpenAPI 品質チェック結果（openapi_spec がある場合）
Step 3: エンドポイント設計
Step 2 の制約に従いエンドポイントを設計する。
REST 命名規約
GET /users # 一覧
POST /users # 作成
GET /users/{id} # 取得
PUT /users/{id} # 全体更新
PATCH /users/{id} # 部分更新
DELETE /users/{id} # 削除
# ネストは 2 階層まで
GET /users/{userId}/orders/{orderId}
# アクションは動詞サブリソースで表現
POST /orders/{id}/cancel
REST 原則チェック（必須）
references/rest-design-guide.md のチェック表に従い全エンドポイントを検証する。 違反があれば同ファイルの警告フォーマットに従いユーザーに提示する。
バージョニング・互換性ポリシー
推奨: URL パス方式（/v1/users）
- non-breaking: 省略可能フィールド追加・新規エンドポイント追加
- breaking: 必須フィールド追加・フィールド削除/型変更・パス変更
- deprecation: 非推奨告知 → 併存期間明示（例: 90日）→ 利用状況モニタリング → 廃止
Step 3 の出力: エンドポイント一覧（メソッド・パス・説明・認証） + 互換性方針メモ
Step 4: リクエスト / レスポンス設計
詳細ガイド: references/rest-design-guide.md
標準レスポンス構造
// 成功（単一リソース）
{ "data": { "id": "123", "name": "Alice" }, "meta": { "requestId": "abc-xyz" } }
// 成功（コレクション）
{ "data": [...], "pagination": { "cursor": "...", "hasNext": true, "total": 500 } }
エラーレスポンス（RFC 7807 Problem Details）
{
"type": "https://api.example.com/errors/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The request body contains invalid fields.",
"instance": "/users/register",
"errors": [{ "field": "email", "message": "Invalid email format" }]
}
Step 4 の出力: リクエスト/レスポンス仕様 + エラーコード定義表
Step 5: OpenAPI スキーマ生成
references/openapi-guide.md を読み込み、OpenAPI 3.0 YAML を生成する。
生成品質要件（必須）
| 要件 | 内容 |
|---|---|
| description | 全 operation・全パスパラメータ・主要スキーマフィールドに記載（制約・認可条件・注意事項を含む） |
| example | 全スキーマにスキーマレベルの example を定義 |
| エラーレスポンス網羅 | 各 operation の発生しうる 4xx/5xx を全パターン列挙 |
| エラー examples | 401/403/404/422/429 にシナリオ別 examples（複数）を定義 |
| $ref 共通化 | 繰り返しスキーマは components で共通化 |
Step 5 の出力: OpenAPI 3.0 YAML（descriptions・examples・error responses を全て含む）
Step 6: レビューと調整
REST 原則レビュー（必須）
生成した OpenAPI 全体を再確認する。新たな違反があれば警告を提示する。
openapi_spec 由来の既存違反には仕様書内（description または x-rest-warning）に注記を追記する。
互換性レビュー（必須）
- breaking 変更の有無を判定する
- breaking なら、メジャーバージョン更新または deprecation 手順を適用する
セキュリティ最小チェック（必須）
- 認可境界: 誰がどのリソース/フィールドを操作できるか明確か
- PII 保護: 収集最小化、マスキング、出力制御、保存方針が定義されているか
- 監査ログ: 認証/認可失敗・更新系操作を追跡可能か
- レート制御: 乱用対策（IP/トークン単位制限、429設計）があるか
- 情報露出: エラーメッセージやレスポンスに内部情報を含めていないか
OpenAPI ドキュメント品質チェック（必須）
| チェック項目 | 基準 |
|---|---|
| operation description | 全 operation に記載されているか |
| parameter description | 全パスパラメータ・クエリパラメータに記載されているか |
| example | 全 schema に example が定義されているか |
| エラーレスポンス網羅 | 各 operation の発生しうる 4xx/5xx が列挙されているか |
| エラー examples | 401/403/404/422/429 にシナリオ別 example があるか |
| components 共通化 | 繰り返しスキーマが $ref で共通化されているか |
Step 2 品質チェック結果の再確認（openapi_spec がある場合）
Step 2 の未対応指摘があれば再度提示し、対応方針を確認する。
Step 6 の出力: レビュー結果（REST 原則 / 互換性 / セキュリティ / ドキュメント品質） + 修正アクション一覧
成果物テンプレート
出力フォーマット（必須）
収集した入力サマリー制約分析サマリー（入力種別ごとの制約と設計方針）OpenAPI 品質チェック結果（openapi_spec がある場合。ユーザー確認後に次へ）エンドポイント一覧（メソッド・パス・説明・認証）互換性ポリシー（breaking/non-breaking/deprecation）OpenAPI 3.0 YAML（解説・スキーマ例・エラーバリエーション含む）セキュリティ最小チェック結果DoD 判定次工程ハンドオフ
エンドポイント一覧表
| メソッド | パス | 説明 | 認証 |
|--------|------|------|------|
| GET | /v1/users | ユーザー一覧取得 | JWT |
| POST | /v1/users | ユーザー作成 | JWT |
| GET | /v1/users/{id} | ユーザー取得 | JWT |
| PUT | /v1/users/{id} | ユーザー更新 | JWT（本人/管理者） |
| DELETE | /v1/users/{id} | ユーザー削除 | JWT（管理者） |
エラーコード定義表
| コード | HTTP ステータス | 発生条件 | 説明 |
|--------|----------------|---------|------|
| USER_NOT_FOUND | 404 | 指定 ID のユーザーが存在しない | ユーザーが見つかりません |
| EMAIL_ALREADY_EXISTS | 409 | 同一メールアドレスが登録済み | メールアドレスが既に使用中 |
| INVALID_TOKEN | 401 | JWT が無効または期限切れ | 認証トークンが無効です |
| INSUFFICIENT_PERMISSION | 403 | 操作に必要なロールがない | 権限が不足しています |
| VALIDATION_ERROR | 422 | リクエストボディのバリデーション失敗 | 入力値が不正です |
| RATE_LIMIT_EXCEEDED | 429 | レートリミット超過 | リクエスト上限を超えました |
Definition of Done（DoD）チェックリスト（必須）
- [ ] 入力を収集し制約分析を完了した
- [ ] openapi_spec がある場合、品質チェック（境界条件・エラーポリシー・矛盾・曖昧さ・REST 原則）を実施しフィードバックした
- [ ] 制約マップに従いエンドポイントを設計した（openapi_spec の既存インターフェースは維持）
- [ ] 品質チェックの指摘事項をユーザーと確認し、対応方針が決まっている
- [ ] REST 原則の違反をチェックし、違反があればユーザーに警告した
- [ ] 既存 IF の REST 原則違反には仕様書内に注記を追記した
- [ ] 互換性ポリシー（breaking/non-breaking/deprecation）が明記されている
- [ ] 全 operation に description が記載されている
- [ ] 全 schema に example が定義されている
- [ ] 全 operation の 4xx/5xx エラーレスポンスが列挙されている
- [ ] エラーレスポンスにシナリオ別 example がある
- [ ] セキュリティ最小チェック5項目が全て確認済み
- [ ] OpenAPI lint を通過している（validate_openapi.py）
- [ ] フロントエンド / DB へのハンドオフ項目が整理されている
次工程ハンドオフ項目（必須）
## フロントエンド向け
- 利用エンドポイント一覧:
- 認証方式・必要スコープ:
- エラーコードと UI ハンドリング方針:
- 互換性注意点（deprecation 期限含む）:
## バックエンド / DB 向け
- 想定アクセスパターン（一覧・検索・集計）:
- インデックス/キャッシュ検討ポイント:
- 監査ログ保存要件:
- PII 取り扱いポリシー:
補助スクリプト
- validate_openapi.py — OpenAPI 3.x YAML / JSON ファイルのスキーマバリデーション
python scripts/validate_openapi.py openapi.yaml
python scripts/validate_openapi.py --strict openapi.yaml # 警告も表示
python scripts/validate_openapi.py --json openapi.yaml # CI 連携用
終了コード: 0 = 通過 / 1 = エラーあり / 2 = ファイル不在・パースエラー
リファレンス
- references/openapi-guide.md — OpenAPI 3.0 スニペット集（descriptions・examples・error responses テンプレート）
- references/rest-design-guide.md — REST 原則チェック表・HTTP ステータスコード・ページネーション・認証設計