api-docs-generator

API 文档生成器

审查 API 端点文档的完整性，生成包含恰当参数说明和示例的增强版文档字符串，记录所有响应代码，并生成 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. 阅读现有文档 — 当前文档字符串、OpenAPI 元数据、内联文档。

阶段 2：审查文档

对于每个端点，检查：

检查项	验证内容	常见问题
端点描述	处理函数是否有文档字符串	缺失或仅为“TODO”
参数说明	每个参数是否都有 description=	路径参数未记录
请求示例	正文模型是否有 example= 或 json_schema_extra	没有请求示例
响应模型	是否指定了 response_model=	返回原始字典
错误响应	是否通过 responses= 记录 4xx/5xx 响应	只记录了 200
标签	端点是否分配到某个标签组	端点未分类

阶段 3：生成增强内容

1. 文档字符串 — 编写清晰的端点描述，说明其用途而非实现方式。为已记录的错误添加 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