api-docs-generator

API ドキュメントジェネレーター

API エンドポイントのドキュメントの網羅性を監査し、適切なパラメーターの説明と例を含む拡張版 docstring を生成し、すべてのレスポンスコードを記載して、Pydantic モデルの例を作成します。自動生成された OpenAPI 仕様と、本当に役立つ API ドキュメントのギャップを埋めます。

参照ファイル

ファイル	内容	読み込むタイミング
references/fastapi-patterns.md	FastAPI 固有のドキュメントパターン、Path／Query／Body パラメーターのドキュメント	FastAPI エンドポイントの場合
references/example-generation.md	現実的なフィールド例の作成、model_config パターン	値の例が必要な場合
references/response-codes.md	標準 HTTP レスポンスのドキュメント、エラーレスポンスのスキーマ	レスポンスのドキュメントが必要な場合
references/openapi-enhancement.md	OpenAPI 仕様の拡張、タグの整理、スキーマのドキュメント	OpenAPI 仕様をレビューする場合

前提条件

• API ソースコード（ルート定義、モデル）へのアクセス
• フレームワークの特定（FastAPI、Flask、Django REST、Express）

ワークフロー

フェーズ 1：エンドポイントを分析する

1. エンドポイントを一覧化する — HTTP メソッド、パス、ハンドラー関数とともに、すべてのルートを列挙します。
2. モデルを特定する — リクエストボディ（Pydantic モデル、データクラス）、レスポンスモデル、クエリパラメーター、パスパラメーターを確認します。
3. 依存関係を整理する — 認証要件、ミドルウェア、共有依存関係を確認します。
4. 既存のドキュメントを読む — 現在の docstring、OpenAPI メタデータ、インラインドキュメントを確認します。

フェーズ 2：ドキュメントを監査する

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

確認項目	確認する内容	よくある不足点
エンドポイントの説明	ハンドラーに docstring がある	ない、または「TODO」
パラメーターの説明	各パラメーターに description= がある	Path パラメーターの説明がない
リクエスト例	ボディモデルに example= または json_schema_extra がある	リクエスト例がない
レスポンスモデル	response_model= が指定されている	生の dict を返す
エラーレスポンス	responses= で 4xx／5xx が記載されている	200 のみ記載
タグ	エンドポイントがタググループに割り当てられている	タグのないエンドポイント

フェーズ 3：拡張を生成する

1. Docstring — 実装方法ではなく、目的を説明する明確なエンドポイントの説明を記述します。記載するエラーには Raises セクションを含めます。
2. パラメーターのメタデータ — Path、Query、Body パラメーターに description、example、ge／le／regex を追加します。
3. モデルの例 — Field(example=...) と、json_schema_extra を含む model_config を追加します。
4. エラーレスポンス — 可能性のあるすべてのエラーステータスコードを、レスポンススキーマとともに記載します。
5. タグ — リソースまたは機能領域ごとにエンドポイントをグループ化します。

フェーズ 4：出力する

カバレッジレポートと拡張したコードを作成します。

出力形式

## API Documentation Audit

### Coverage Summary
| Metric | Count | Documented | Coverage |
|--------|-------|------------|----------|
| Endpoints | {N} | {M} | {%} |
| Parameters | {N} | {M} | {%} |
| Response codes | {N} | {M} | {%} |
| Models with examples | {N} | {M} | {%} |

### Gaps Identified

| # | Endpoint | Issue | Severity |
|---|----------|-------|----------|
| 1 | `{METHOD} {path}` | {issue} | {High/Medium/Low} |

### Enhanced Code

#### `{METHOD} {path}`

```python
@router.{method}(
    "{path}",
    response_model={ResponseModel},
    summary="{Short summary}",
    responses={{
        404: {{"description": "{Not found description}"}},
        422: {{"description": "Validation error"}},
    }},
    tags=["{tag}"],
)
async def {handler}(
    {param}: {type} = Path(..., description="{description}", example={example}),
) -> {ResponseModel}:
    """
    {Full description of what this endpoint does.}

    {Additional context about behavior, side effects, or important notes.}

    Raises:
        404: {Entity} not found
        403: Insufficient permissions
    """

モデル：{ModelName}

class {ModelName}(BaseModel):
    {field}: {type} = Field(..., description="{description}", example={example})

    model_config = ConfigDict(
        json_schema_extra={{
            "example": {{
                "{field}": {example_value},
            }}
        }}
    )

## Calibration Rules

1. **Describe behavior, not implementation.** "Retrieves the user's profile" is good.
   "Calls `db.query(User).filter_by(id=id).first()`" is implementation leakage.
2. **Realistic examples.** `"[email protected]"` not `"string"`. `42` not `0`.
   Examples serve as documentation — they should look like real data.
3. **Document every error code.** If the endpoint can return 404, document it. Users
   should never encounter an undocumented error response.
4. **Consistent style.** All endpoints in the same API should use the same documentation
   patterns — same tag naming, same description style, same example format.
5. **Don't duplicate the type system.** If the parameter type is `int`, don't write
   "An integer" as the description. Write what the integer represents: "Unique user
   identifier."

## Error Handling

| Problem | Resolution |
|---------|------------|
| Non-FastAPI framework | Adapt patterns. Document the HTTP contract regardless of framework. |
| No type hints on handlers | Infer types from usage, document uncertainty, suggest adding type hints. |
| Massive API (50+ endpoints) | Prioritize undocumented and public endpoints. Batch output by resource. |
| Generated API (OpenAPI → code) | Document at the spec level, not the generated code level. |
| Authentication varies by endpoint | Document auth requirements per endpoint group. |

## When NOT to Generate

Push back if:
- The API design itself is wrong (bad URL patterns, wrong HTTP methods) — fix the API first
- The user wants SDK generation from OpenAPI — different tool
- The code is a prototype that will change significantly — document after stabilization