用Gemini做API文档生成：从代码注释到OpenAPI规范的自动化

在后端项目里，API文档常常是“上线前补一下”的东西，结果接口一多，文档和代码就开始不同步。前端按文档联调发现字段不对，测试按文档造数据发现状态码不全，后端再回头翻代码确认，效率很低。我最近在整理接口文档自动化方案时，会先通过 t.877ai.cn 这类 AI模型聚合平台 对比不同模型对代码注释、Controller逻辑和结构化规范的理解能力，再决定是否把Gemini接入到文档生成流程里。相比手写文档，Gemini更适合做“初稿生成”和“规范补全”。

API文档生成的核心，不是把注释翻译成中文，而是从代码里提取稳定信息。列如接口路径、请求方法、Header参数、Query参数、Body结构、响应字段、错误码、鉴权方式等。这些信息分散在路由定义、DTO类、注解、校验规则、业务代码和返回对象里，人工整理很容易漏。

以常见的Spring Boot项目为例，一个接口可能写在Controller里，参数定义在Request对象中，返回结果封装在统一的Result类里，字段校验又写在@NotNull、@Size、@Pattern等注解上。如果只靠简单脚本扫描注解，能拿到一部分信息，但很难生成一份可读性较好的说明。Gemini的价值就在这里：它能综合代码上下文，把零散信息组织成接近文档的结构。

一个比较实用的流程是：先用脚本扫描项目，提取Controller、DTO、VO、枚举、注释和路由信息；然后把这些内容按接口维度拼成输入；再让Gemini生成OpenAPI YAML或JSON；最后用校验工具检查格式，并由开发人员审核重点字段。这样比直接把整个项目丢给模型更稳，也更节省上下文。

提示词设计要尽量明确。不要只说“帮我生成接口文档”，而是告知模型：请根据以下Java代码生成OpenAPI 3.0规范，包含路径、请求方法、参数、requestBody、responses、schema、字段说明和必填项；不要编造代码中不存在的字段；如果信息不确定，用description标注“需确认”。这样的约束能减少模型自由发挥。

如果代码注释写得比较规范，Gemini生成效果会更好。列如字段上有“用户ID”“订单状态：0待支付，1已支付，2已撤销”这样的说明，模型可以直接转换成schema描述和枚举说明。反过来，如果代码里只有id、type、flag这类字段，没有注释，也没有枚举定义，模型只能根据命名猜测，准确性就会下降。

从实践看，API文档自动化最好分三层做。第一层是确定性信息，由程序直接解析，列如URL、HTTP方法、参数类型、是否必填。第二层是语义信息，由Gemini辅助生成，列如字段解释、接口用途、示例请求、示例响应。第三层是人工确认，列如业务规则、异常场景、权限说明。这三层分开后，整个流程会更可靠。

OpenAPI规范是这个方案的关键落点。许多团队以前写Markdown文档，看起来方便，但机器不容易消费。OpenAPI的好处是可以直接导入Swagger UI、Postman、Apifox等工具，也能用于生成SDK、Mock服务和接口测试用例。换句话说，文档不再只是“给人看的说明”，而是可以进入研发流程的结构化资产。

和传统Swagger注解相比，Gemini方案更灵活。Swagger注解适合在代码阶段同步维护，但许多老项目没有完整注解，补起来成本很高。Gemini可以基于现有代码和少量注释生成初版规范，适合存量项目治理。但它也有短板：生成内容需要校验，不能默认完全正确。尤其是鉴权逻辑、错误码和业务限制，必须由开发确认。

这里有个容易踩坑的点：不要一次生成全项目文档。接口多了后来，上下文会很长，模型容易遗漏或混淆。更好的方式是按模块或按Controller生成，每次处理十几个接口以内。生成后再通过脚本合并OpenAPI文件，并做schema去重。这样可维护性更好，也方便定位问题。

对于响应结构，也提议统一处理。如果项目里所有接口都返回类似Result<T>结构，提示词里要说明这一点：外层包含code、message、data，真正业务数据在data中。否则模型可能只生成业务对象，忽略统一响应包装，导致前端导入后结构不一致。

异常响应也不能忽略。许多接口文档只写200成功，实际联调时却频繁遇到400、401、403、500等状态。可以让Gemini根据校验注解、权限注解和业务代码补充常见错误响应，但最终错误码表最好来自项目统必定义。模型可以整理，规则要以代码仓库为准。

在CI/CD里，这套方案还可以继续自动化。列如每次合并代码时，脚本检测Controller或DTO是否变更；如果变更，就触发文档重新生成；生成结果提交到文档分支或产出构建产物；再由开发Review差异。这样API文档就不再依赖个人习惯，而是变成工程流程的一部分。

从趋势看，API文档正在从“人工维护”走向“代码驱动 + AI补全”。确定性部分交给静态分析，表达性部分交给大模型，最终结果进入OpenAPI生态。未来团队之间的差距，不在于有没有文档，而在于文档能不能持续更新、能不能参与测试、能不能服务联调。

我的观点是，Gemini做API文档生成，最适合解决“存量项目文档缺失”和“文档初稿成本高”这两个问题。它不能替代开发对接口语义的确认，但可以把大量重复整理工作前置自动化。只要把代码解析、模型生成、规范校验和人工Review串起来，从代码注释到OpenAPI规范的自动化就能真正落地，而不是停留在一次性演示。