Back to Details

api-docs-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Docs Generator

API文档生成工具

Audits API endpoint documentation for completeness, generates enhanced docstrings with proper parameter descriptions and examples, documents all response codes, and produces Pydantic model examples — bridging the gap between auto-generated OpenAPI specs and genuinely useful API documentation.
审核API端点文档的完整性，生成包含恰当参数描述和示例的增强型文档字符串，记录所有响应码，并生成Pydantic模型示例——填补自动生成的OpenAPI规范与真正实用的API文档之间的差距。

Reference Files

参考文件

FileContentsLoad When
references/fastapi-patterns.md
FastAPI-specific documentation patterns, Path/Query/Body parameter docsFastAPI endpoint
references/example-generation.md
Creating realistic field examples, model_config patternsExample values needed
references/response-codes.md
Standard HTTP response documentation, error response schemasResponse documentation needed
references/openapi-enhancement.md
OpenAPI spec enrichment, tag organization, schema documentationOpenAPI spec review
文件路径内容加载时机
references/fastapi-patterns.md
FastAPI专属的文档模式、路径/查询/请求体参数文档处理FastAPI端点时
references/example-generation.md
创建真实字段示例、model_config模式需要生成示例值时
references/response-codes.md
标准HTTP响应文档、错误响应 schema需要编写响应文档时
references/openapi-enhancement.md
OpenAPI规范增强、标签组织、schema文档审核OpenAPI规范时

Prerequisites

前提条件

  • Access to the API source code (route definitions, models)
  • Framework identification (FastAPI, Flask, Django REST, Express)
  • 能够访问API源代码（路由定义、模型）
  • 已识别框架类型（FastAPI、Flask、Django REST、Express）

Workflow

工作流程

Phase 1: Analyze Endpoints

第一阶段：分析端点

  1. Inventory endpoints — List all routes with HTTP method, path, handler function.
  2. Identify models — Request bodies (Pydantic models, dataclasses), response models, query parameters, path parameters.
  3. Map dependencies — Authentication requirements, middleware, shared dependencies.
  4. Read existing docs — Current docstrings, OpenAPI metadata, inline documentation.
  1. 盘点端点 —— 列出所有路由，包含HTTP方法、路径、处理函数。
  2. 识别模型 —— 请求体（Pydantic模型、数据类）、响应模型、查询参数、路径参数。
  3. 映射依赖项 —— 认证要求、中间件、共享依赖。
  4. 读取现有文档 —— 当前的文档字符串、OpenAPI元数据、内联文档。

Phase 2: Audit Documentation

第二阶段：审核文档

For each endpoint, check:
CheckWhat to VerifyCommon Gap
Endpoint descriptionHandler has a docstringMissing or "TODO"
Parameter descriptionsEach param has 
description=
Path params undocumented
Request exampleBody model has 
example=
or 
json_schema_extra
No request example
Response model
response_model=
specified		Returns raw dict
Error responses4xx/5xx documented with 
responses=
Only 200 documented
TagsEndpoint assigned to a tag groupUntagged endpoints
针对每个端点，检查以下内容：
检查项验证内容常见缺失
端点描述处理函数是否有文档字符串缺失或标记为"TODO"
参数描述每个参数是否包含
description=
路径参数未文档化
请求示例请求体模型是否有
example=
或
json_schema_extra
无请求示例
响应模型是否指定了
response_model=
返回原始字典
错误响应是否通过
responses=
记录了4xx/5xx响应		仅记录了200响应
标签端点是否分配到标签组端点未标记标签

Phase 3: Generate Enhancements

第三阶段：生成增强内容

  1. Docstrings — Write clear endpoint descriptions that explain purpose, not implementation. Include Raises section for documented errors.
  2. Parameter metadata — Add 
    description
    , 
    example
    , 
    ge
    /
    le
    /
    regex
    to Path, Query, Body parameters.
  3. Model examples — Add 
    Field(example=...)
    and 
    model_config
    with 
    json_schema_extra
    .
  4. Error responses — Document every possible error status code with response schema.
  5. Tags — Group endpoints by resource or feature area.
  1. 文档字符串 —— 编写清晰的端点描述，说明用途而非实现细节。包含已记录错误的Raises章节。
  2. 参数元数据 —— 为路径、查询、请求体参数添加
    description
    、
    example
    、
    ge
    /
    le
    /
    regex
    。
  3. 模型示例 —— 添加
    Field(..., example=...)
    和带有
    json_schema_extra
    的
    model_config
    。
  4. 错误响应 —— 记录所有可能的错误状态码及对应的响应schema。
  5. 标签 —— 按资源或功能领域对端点进行分组。

Phase 4: Output

第四阶段：输出

Produce a coverage report and enhanced code.
生成覆盖率报告和增强后的代码。

Output Format

输出格式

undefined
undefined

API Documentation Audit

API文档审核报告

Coverage Summary

覆盖率摘要

MetricCountDocumentedCoverage
Endpoints{N}{M}{%}
Parameters{N}{M}{%}
Response codes{N}{M}{%}
Models with examples{N}{M}{%}
指标总数已文档化覆盖率
端点{N}{M}{%}
参数{N}{M}{%}
响应码{N}{M}{%}
带示例的模型{N}{M}{%}

Gaps Identified

识别出的缺失项

#EndpointIssueSeverity
1
{METHOD} {path}
{issue}{High/Medium/Low}
序号端点问题严重程度
1
{METHOD} {path}
{issue}{高/中/低}

Enhanced Code

增强后的代码

{METHOD} {path}

{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
    """
python
@router.{method}(
    "{path}",
    response_model={ResponseModel},
    summary="{简短摘要}",
    responses={{
        404: {{"description": "{资源未找到描述}"}},
        422: {{"description": "验证错误"}},
    }},
    tags=["{tag}"],
)
async def {handler}(
    {param}: {type} = Path(..., description="{描述}", example={example}),
) -> {ResponseModel}:
    """
    {该端点的完整功能描述}

    {关于行为、副作用或重要注意事项的额外说明}

    Raises:
        404: {实体}未找到
        403: 权限不足
    """

Model: 
{ModelName}

模型：
{ModelName}

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

    model_config = ConfigDict(
        json_schema_extra={{
            "example": {{
                "{field}": {example_value},
            }}
        }}
    )
text
undefined
python
class {ModelName}(BaseModel):
    {field}: {type} = Field(..., description="{描述}", example={example})

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

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. 
    "alice@example.com"
    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."
  1. 描述行为而非实现细节。"获取用户资料"是合适的描述，"调用
    db.query(User).filter_by(id=id).first()
    "属于实现细节泄露，不应出现在文档中。
  2. 使用真实示例。使用
    "alice@example.com"
    而非
    "string"
    ，使用
    42
    而非
    0
    。示例本身就是文档的一部分，应贴近真实数据。
  3. 记录所有错误码。如果端点可能返回404，就必须记录它。用户不应遇到未文档化的错误响应。
  4. 保持风格一致。同一API中的所有端点应使用相同的文档模式——相同的标签命名、相同的描述风格、相同的示例格式。
  5. 不要重复类型系统信息。如果参数类型是
    int
    ，不要写"一个整数"作为描述，而是说明该整数代表什么："唯一用户标识符"。

Error Handling

错误处理

ProblemResolution
Non-FastAPI frameworkAdapt patterns. Document the HTTP contract regardless of framework.
No type hints on handlersInfer 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 endpointDocument auth requirements per endpoint group.
问题解决方法
非FastAPI框架调整文档模式。无论使用何种框架，都要记录HTTP契约。
处理函数没有类型提示从使用情况推断类型，记录不确定性，并建议添加类型提示。
大型API（50+端点）优先处理未文档化的公开端点。按资源分批输出结果。
生成式API（OpenAPI → 代码）在规范层面进行文档化，而非生成的代码层面。
端点间认证要求不同按端点组记录认证要求。

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
undefined
在以下情况下，应拒绝生成请求：
  • API设计本身存在问题（不良URL模式、错误的HTTP方法）—— 先修复API设计
  • 用户希望从OpenAPI生成SDK—— 这属于不同工具的功能范畴
  • 代码是会大幅变更的原型—— 待代码稳定后再进行文档化
undefined