バックエンド実装コードからOpenAPI 3.1準拠のYAMLドキュメントを生成・更新するスキル。スタンドアロンで使えるし、fullstack-pipelineの一部としても呼ばれる。 対応フレームワーク: FastAPI / Express / Hono / NestJS / Gin / Echo / Spring Boot。Pydantic・Zod・struct tag・DTOからスキーマ抽出、認証方式（Bearer/APIKey/OAuth2）も自動検出する。 使用するケース: 「APIドキュメントを作って」「OpenAPIを生成」「Swagger定義を書いて」「openapi.yamlを更新」「エンドポイント一覧をまとめて」など、コードからAPI仕様を生成・更新する依頼全般。 使わないケース: ドキュメントから実装を生成する逆方向の作業、AsyncAPI/GraphQL等のREST以外のAPI、手動で書かれた仕様書のレビューのみ。 既存openapi.yamlがある場合は差分更新し、手書きされたdescription/exampleは保持する。
バックエンド実装コードを読み取り、OpenAPI 3.1準拠のYAMLドキュメントを生成する。
docs/openapi.yaml に出力するまず対象プロジェクトの構造を把握する。以下を確認すること:
openapi.yaml や swagger.json があるかフレームワークの特定には以下のファイルを確認する:
package.json → Express / Hono / NestJSpyproject.toml / requirements.txt → FastAPI / Django RESTgo.mod → Gin / Echopom.xml / build.gradle → Spring Bootフレームワークごとのルーティングパターンからエンドポイントを抽出する。
各エンドポイントについて以下を収集する:
| 項目 | 説明 |
|---|---|
| パス | /api/v1/users/{id} のようなURLパス |
| HTTPメソッド | GET, POST, PUT, PATCH, DELETE |
| 概要 (summary) | エンドポイントの短い説明 |
| タグ | リソースやドメインによるグループ分け |
| パスパラメータ | {id} のようなURL内パラメータ |
| クエリパラメータ | ?page=1&limit=10 のようなクエリ文字列 |
| リクエストボディ | POST/PUT/PATCHのリクエスト本文スキーマ |
| レスポンス | ステータスコード別のレスポンススキーマ |
| 認証要否 | 認証が必要かどうか |
FastAPI (Python)
@app.get(), @router.post() などのデコレータからパスとメソッドを取得response_model からレスポンススキーマを特定Field() から description や example を取得Depends() から認証ミドルウェアを検出Express / Hono (TypeScript/JavaScript)
router.get(), app.post() からパスとメソッドを取得Gin / Echo (Go)
r.GET(), e.POST() からパスとメソッドを取得c.Bind(), c.JSON() から入出力の型を推定json:, binding:）からフィールド情報を取得Spring Boot (Java/Kotlin)
@GetMapping, @PostMapping などのアノテーションからパスとメソッドを取得@RequestBody, @PathVariable, @RequestParam から入力パラメータを特定@PreAuthorize, @Secured から認証要件を検出以下の構造でOpenAPI 3.1準拠のYAMLを生成する: