API文書生成 は何をしますか?
このスキルは、コードベース内のAPIルートファイルからOpenAPI 3.0(Swagger)文書を自動生成します。
このスキルを使用するタイミング
- API文書の生成をユーザーから依頼された場合
- REST APIエンドポイントを扱っている場合
- OpenAPI/Swagger仕様を作成または更新する必要がある場合
- Express、FastAPI、Flask、NestJS、または類似フレームワークのAPI文書を設定する場合
手順
1. APIルートの検出
コードベース内でAPIルート定義を検索します:
- Express/Node.js:
app.get()、app.post()、router.get()などを探す - FastAPI/Python:
@app.get()、@router.post()などのデコレータを探す - Flask:
@app.route()デコレータを探す - NestJS:
@Get()、@Post()、@Controller()デコレータを探す - Rails:
config/routes.rb内のルートを探す
Globを使用してルートファイルを検索します(例:**/*routes*.{js,ts,py}、**/controllers/**/*.{js,ts})
2. ルートパターンの分析
検出した各ルートについて以下を抽出します:
- HTTPメソッド: GET、POST、PUT、PATCH、DELETE
- パス: エンドポイントURL(例:
/api/users/:id) - パラメータ: パスパラメータ、クエリパラメータ、リクエストボディ
- レスポンス: 期待されるレスポンス構造
- 認証: 認証が必要かどうか
- 説明: ルート近くのコメントやdocstring
3. OpenAPI仕様の生成
OpenAPI 3.0仕様ファイル(通常 openapi.yaml または swagger.json)を作成または更新します:
templates/openapi-3.0.yamlのテンプレートから開始する- 各ルートをOpenAPIパスオブジェクトにマッピングする
- JSON Schemaを使用してリクエスト/レスポンススキーマを定義する
- パラメータ定義(パス、クエリ、ボディ)を含める
- 検出された認証スキーム(Bearer、API Key、OAuth2)を追加する
- タグでエンドポイントをグループ化する(例:「Users」「Products」「Auth」)
4. 完全性の検証
生成された文書に以下が含まれているか確認します:
- 検出されたすべてのエンドポイント
- 正確なHTTPメソッドとパス
- 可能な場合はリクエスト/レスポンスの例
- エラーレスポンス(400、401、404、500など)
- セキュリティ要件
5. 出力場所
- プロジェクトルートに
openapi.yamlとして保存する、または docs/またはapi/ディレクトリが存在する場合はそこに保存する- 不明な場合はユーザーに希望場所を尋ねる
フレームワーク固有の注意点
Express/Node.js
- 認証/バリデーションに影響するルートミドルウェアを確認する
- リクエストバリデータ(Joi、express-validatorなど)を探す
- エンドポイントの説明としてJSDocコメントを抽出する
FastAPI
- FastAPIはOpenAPI文書を自動生成しますが、このスキルで拡張できます
- リクエスト/レスポンススキーマ用にPydanticモデルを抽出する
response_modelとstatus_codeパラメータを確認する
NestJS
- スキーマ用のDTO(データ転送オブジェクト)を探す
- Swaggerデコレータ(
@ApiOperation、@ApiResponse)を確認する - コントローラーおよびメソッドデコレータからメタデータを抽出する
ベストプラクティス
- 既存のスキーマを使用する: コードベースにTypeScriptインターフェース、Pydanticモデルなどがある場合は、正確なスキーマに使用する
- 例を含める: テストからリクエスト/レスポンスの例があれば追加する
- 論理的にグループ化する: タグを使用してエンドポイントをリソースまたは機能領域で整理する
- 適切にバージョニングする: コードベースのAPIバージョンを使用する(例:「1.0.0」)
- 説明を追加する: エンドポイントの説明にコードコメント/docstringを使用する
関連ファイル
templates/openapi-3.0.yaml: 基本OpenAPIテンプレートexamples.md: フレームワーク固有の例