api-doc-generator

API ドキュメント生成ツール

信頼できる成果物に基づいて API を文書化し、確認済みの事実と推測を区別します。

ソースの優先順位

利用可能なソースのうち、次の順序で信頼性の高いものを使用します。

1. リポジトリにコミット済みの OpenAPI／Swagger コントラクトと生成済みスキーマ。
2. フレームワークのルート定義とアノテーション。
3. リクエスト／レスポンスモデルと検証ルール。
4. 認証、ミドルウェア、例外処理、エラーカタログ。
5. 統合テストとコントラクトテスト。
6. ユーザーが明示的に許可したランタイムの観察結果。

ソース間で内容が異なる場合、黙って一方を選ぶのではなく、その不一致を報告します。

フレームワーク別の参照先

関連する参照先のみを確認します。

• OpenAPI ファースト：references/openapi-first.md
• Java／Kotlin Spring：references/spring.md
• Python FastAPI：references/fastapi.md
• TypeScript NestJS：references/nestjs.md
• JavaScript／TypeScript Express：references/express.md
• Go Gin：references/gin.md

一通りの例が役立つ場合に限り、references/scan-and-generate-example.md を使用します。

リポジトリにコミット済みの OpenAPI ドキュメントがある場合、説明文の作成前に、次のコマンドで決定的な一覧を生成します。

python3 scripts/inventory_openapi.py path/to/openapi.yaml --output docs/api-inventory.md

このスクリプトは、--force が明示的に指定されない限り、既存の出力を上書きしません。

ワークフロー

1. 調査する

1. プロジェクトのフレームワーク、モジュール、既存の API コントラクト、ドキュメントの規約を特定します。
2. ユーザーの指示から対象範囲を判断します。より狭い範囲が指定されていない場合に限り、API 全体を対象として推定します。
3. ルート登録、ベースパス、バージョンプレフィックス、セキュリティミドルウェア、モデル、バリデーター、エラー処理、テストの場所を特定します。
4. 生成ファイルを特定し、信頼できる一次情報源と取り違えないようにします。

2. エンドポイント一覧を作成する

各エンドポイントについて、次の項目を記録します。

項目	要件
メソッドとパス	すべてのプレフィックスとルートグループを解決します
オペレーションの識別情報	ハンドラー／コントローラーと、安定したオペレーション名
目的	コード／コメントから導き、推測である場合は明記します
認証	方式、スコープ／ロール、認証不要の例外
リクエスト	パス／クエリ／ヘッダー／Cookie／ボディのフィールドと検証
レスポンス	ステータスコード、コンテンツタイプ、スキーマ、ラッパー
エラー	ハンドラー、ミドルウェア、テスト、カタログで裏付けられたエラーのみ
根拠	使用したコントラクトまたはソースの場所

例の値、文書化されていないエラーコード、必須フラグ、レスポンスフィールドを捏造しないでください。

3. スキーマを解決する

• ネストされたモデル参照と汎用レスポンスラッパーをたどります。
• null 許容性、オプション性、列挙型、書式、範囲、長さの制約を維持します。
• ページネーションとリストのエンベロープ規約を特定します。
• 再帰的スキーマまたはポリモーフィックなスキーマを明示します。
• 例に含まれるシークレットと個人データをマスキングします。

4. ドキュメントを生成する

リポジトリの既存の規約に従います。規約がない場合は、assets/templates/ からテンプレートを 1 つ選び、docs/ 配下の提案パスに書き込みます。書き込む前に、出力先と、そのファイルがすでに存在するかどうかを報告します。

各エンドポイントについて、次の項目を含めます。

1. 概要と根拠のステータス
2. メソッドと完全なパス
3. 認証／認可
4. パラメーターとリクエストボディ
5. レスポンスと、根拠のあるエラー
6. 最小限の有効な例
7. ソースの場所

5. 検証する

• 文書化したルートを、特定した一覧と照合します。
• パス変数とリクエストフィールドを、バリデーター／モデルと照合します。
• レスポンスとエラーのステータスコードを、コードまたはコントラクトと照合します。
• 内部リンクとアンカーを確認します。
• 未解決の不一致と推測したフィールドに印を付けます。
• API を実際に実行していない場合、ランタイムで検証済みだと主張しません。

根拠のラベル

確実性が重要な場合は、次のラベルを使用します。

• 已确认：契约 — チェックイン済みの API 契約に記載されています。
• 已确认：源码 — ルート／モデル／ハンドラーのソースに記載されています。
• 已确认：测试 — テストで検証されています。
• 推断 — 妥当な推測ですが、明示的には指定されていません。
• 待确认 — 根拠が矛盾しているか、不足しています。

完了時の報告事項

生成／更新したファイル、ドキュメント化したエンドポイントの数、使用した信頼できる情報源、契約とソースの不一致、推定したフィールド、および根拠が不十分なために対象外としたエンドポイントを報告してください。