api-doc-generator

API Doc Generator

コードから API ドキュメントを自動生成し、OpenAPI/Swagger 仕様に対応します。

概要

プロジェクトのコード内にあるルートとインターフェース定義をスキャンし、パラメーター、戻り値、コメントを自動的に抽出して、OpenAPI 3.0 仕様に準拠した YAML ファイルとインタラクティブなドキュメントページを生成します。

使用する場面

• ユーザーが API ドキュメントの生成を希望している
• ユーザーが OpenAPI、Swagger、または API ドキュメントについて言及している
• ユーザーがドキュメント化が必要な REST/GraphQL エンドポイントを持っている
• ユーザーが「API ドキュメントを生成」／「API ドキュメントを作成」と言っている
• ユーザーが /api-doc-generator を入力している

使用しない場面：

• ユーザーが README に API の説明を書きたいだけの場合
• ユーザーが API のテストを希望している場合（テストツールを使用してください）
• ユーザーのプロジェクトに HTTP エンドポイントがない場合
• ユーザーが SDK／クライアントコードの生成を希望している場合
• ユーザーが API のモックを希望している場合（Mockoon、WireMock を使用してください）

基本パターン

ステップ 1：フレームワークとルートを検出する

フレームワーク	検出方法	ルートの抽出
Express/Koa/Fastify	require('express') ／ルートファイル	app.get/post/put/delete をスキャン
Next.js API Routes	app/api/ ディレクトリ	route.ts ファイルをスキャン
Gin (Go)	r.GET/POST	router の登録をスキャン
Flask/FastAPI (Python)	@app.route ／ @router	デコレーターをスキャン
Spring Boot (Java)	@GetMapping ／ @RestController	アノテーションをスキャン

# 快速检测
grep -rE "app\.(get|post|put|delete|patch)" --include="*.ts" --include="*.js" --include="*.go" --include="*.py" -l

ステップ 2：インターフェース情報を抽出する

各ルートから次の情報を抽出します：

• HTTP メソッド + パス
• リクエストパラメーター：query、params、body（型定義／JSDoc／アノテーションから推定）
• レスポンス形式：return 文または型定義から推定
• コメント／説明：コードコメントから抽出
• 認証要件：auth middleware の有無を確認

ステップ 3：OpenAPI YAML を生成する

templates/openapi.yaml（{{variable}} と {{#each}} のプレースホルダーを含む Handlebars テンプレート）をベースとして使用します。抽出したインターフェース情報を該当する変数に挿入し、レンダリングした結果を openapi.yaml として出力します。レンダリング結果はおおむね次のようになります：

openapi: 3.0.3
info:
  title: 项目名 API
  version: 1.0.0
paths:
  /api/users:
    get:
      summary: 获取用户列表
      parameters: [...]
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

ステップ 4：インタラクティブなドキュメントページを生成する（任意）

Swagger UI または Redoc を使用して、閲覧可能な HTML ページを生成します：

# 使用 npx 快速预览
npx @redocly/cli preview-docs openapi.yaml

クイックリファレンス

/api-doc-generator                    # 扫描当前项目，生成 openapi.yaml
/api-doc-generator --format yaml      # 输出 YAML（默认）
/api-doc-generator --format json      # 输出 JSON
/api-doc-generator --preview          # 生成并预览交互式文档

パラメーター	説明	デフォルト値
--format	出力形式 yaml / json	yaml
--preview	インタラクティブな HTML ドキュメントを生成	false

よくある間違い

間違い	正しい方法	理由
1 つのファイルだけをスキャンする	すべてのルートファイルを再帰的にスキャンする	インターフェースを見落とす可能性があります
リクエストボディの構造をハードコーディングする	型定義から推定する	ドキュメントとコードの一貫性を保てます
ネストされたルートを処理しない	ルート登録の完全なパスを解析する	/api/users/:id の :id を注記する必要があります
エラーレスポンスを無視する	4xx/5xx レスポンスを追加する	完全な API ドキュメントにはエラーの説明が必要です
認証要件を無視する	auth middleware を確認する	クライアントは認証が必要なインターフェースを把握する必要があります