13 - API 文档生成¶

项目背景与目标¶

某微服务架构企业拥有 300+ 服务、上万个 API，但文档与代码严重脱节：文档靠人工维护，更新滞后，字段说明缺失，调用方频繁踩坑；新人对接一个服务平均要花 2 天读代码。企业希望构建自动 API 文档生成系统，从代码与注释自动提取接口结构、生成说明文档、补充示例代码与调用说明，并随代码提交自动更新，使文档与代码始终同步，API 字段说明覆盖率 ≥ 95%。

核心目标： 1. 自动从代码提取 API 结构（路径/参数/返回/错误码） 2. 字段说明自动生成，覆盖率 ≥ 95% 3. 自动生成示例请求/响应代码（多语言） 4. 文档随代码提交自动更新

预期价值：文档与代码同步、降低对接成本、提升 API 一致性、新人快速上手。

需求分析¶

用户角色与场景 - API 提供者：定义接口、补充说明、发布文档 - API 调用方：查阅文档、复制示例、调试 - 架构师：审查 API 设计一致性

功能需求列表 - 多语言代码解析（Java Spring / Go Gin / Python FastAPI / Node Express） - 注释/注解提取（OpenAPI/Swagger 注解 + 行注释） - 字段说明自动补全（LLM 根据字段名与上下文生成） - 示例代码生成（cURL/Java/Python/JS） - 错误码与状态说明 - 调用关系与依赖图 - 文档站点自动构建与发布 - 变更检测与版本对比（diff 提示 Breaking Change）

非功能需求 - 性能：单服务文档生成 < 1 分钟 - 准确性：字段说明语义正确率 ≥ 90% - 可用性：文档站点 99.9% - 集成：CI/CD 自动触发

约束条件：需兼容现有 OpenAPI 规范；内部框架需自定义解析。

技术选型说明¶

层次	技术选择	选型理由
代码解析	Tree-sitter + AST	多语言统一解析
注解解析	OpenAPI Parser	标准
LLM	Qwen2.5-Coder-32B	字段说明与示例生成
文档站点	Docusaurus / VitePress	现代、可搜索
后端	Python + CI Pipeline	解析与生成
部署	CI/CD + 静态站点	自动化

架构设计¶

flowchart LR
    REPO[代码仓库] --> CI[CI 触发]
    CI --> PARSE[AST 解析 Tree-sitter]
    PARSE --> EXT[注解/注释提取]
    EXT --> MERGE[结构合并]
    MERGE --> LLM[LLM 补全字段说明]
    LLM --> EX[示例代码生成]
    EX --> DIFF[变更对比 Breaking]
    DIFF --> BUILD[文档站点构建]
    BUILD --> SITE[文档站点]
    BUILD --> API[OpenAPI Spec]

核心是「AST 解析 + 注解提取 + LLM 补全 + 示例生成 + 变更检测」。优先使用代码中的 OpenAPI 注解与注释，缺失部分由 LLM 根据字段名、类型、上下文补全说明，最后生成多语言示例与文档站点。

关键模块实现思路¶

模块1：多语言 AST 解析¶

思路：用 Tree-sitter 解析各语言 AST，识别路由定义（如 Spring 的 @RequestMapping）、参数类型、返回类型；提取 DTO 类的字段与注释。
关键点：内部框架自定义装饰器需写适配规则；解析结果转为统一中间表示（IR）。

模块2：注解与注释提取¶

思路：解析 OpenAPI/Swagger 注解（@Operation、@Parameter）提取已有说明；提取字段上方行注释；将注解与注释合并到 IR。
关键点：已有说明优先于 LLM 生成，避免覆盖人工说明。

模块3：LLM 字段说明补全¶

思路：对缺失说明的字段，LLM 根据字段名（驼峰转词）、类型、业务上下文（所在 DTO、接口路径）生成说明；批量调用降低成本。

示意：

def enrich_fields(fields, context):
    missing = [f for f in fields if not f.desc]
    prompt = f"上下文:{context};为字段生成说明:{missing}"
    descs = llm.parse(prompt)
    return merge(fields, descs, prefer_existing=True)

模块4：示例代码生成与变更检测¶

思路：基于接口结构生成 cURL/多语言 SDK 示例，参数填合理示例值（按类型推断）；变更检测对比上次 Spec，标注新增/删除/类型变更字段为 Breaking Change。
关键点：Breaking Change 在文档与 PR 中显眼提示，防止不兼容升级。

核心流程详解¶

流程1：新服务文档生成¶

服务首次接入，CI 触发解析
AST 提取 20 个接口、50 个 DTO
注解已有说明 30%，LLM 补全剩余 70%
生成 cURL/Java/Python 示例
构建文档站点发布，调用方可搜索查阅

流程2：接口变更检测¶

开发者修改订单接口，删除「couponId」字段
CI 解析后与上次 Spec diff，识别字段删除为 Breaking
PR 评论标红 Breaking Change，通知调用方
文档站点更新版本并显示变更日志

部署与优化建议¶

部署架构：CI Pipeline 触发解析；文档站点静态部署 CDN；Spec 存 Git。
性能优化：增量解析仅变更文件；LLM 补全批量调用。
成本控制：已有说明不调 LLM；字段说明缓存复用。

常见问题与解决方案¶

LLM 说明语义偏差 → 已有注释优先；说明可被开发者编辑覆盖并标记「人工确认」。
内部框架无法解析 → 编写 Tree-sitter 查询规则适配自定义装饰器。
示例值不合理 → 按类型与字段名规则推断（手机号字段填示例手机号）。

扩展方向¶

在线调试：文档站点内嵌 API 调试器。
API 一致性审查：检测命名、分页、错误码规范一致性。
SDK 自动生成：基于 Spec 自动生成多语言 SDK。