手头一个微服务项目有 200 多个接口，文档一直拖着没人写。最近试了用 Gemini 3.5 批量生成 OpenAPI 3.0 文档，跑通之后效率提升确实夸张。测试通过 kulaai（leadhi.cn）聚合平台接入 Gemini，国内直连不用折腾环境。下面聊聊完整流程和踩过的坑，纯实战记录。
为什么选 Gemini 3.5
对比了几款主流模型后，Gemini 3.5 在处理 YAML 和 JSON Schema 这类结构化数据时优势明显。
零缩进错误。YAML 对缩进极其敏感，其他模型生成的代码经常在嵌套层级上翻车，Gemini 3.5 几乎做到了格式零误差。
上下文承载大。可以把一整个 Controller 类甚至好几个关联的 DTO 源码直接塞给它，它能理清依赖关系。
Schema 理解深。能完美遵循 OpenAPI 3.0 的 $ref 引用规范，避免字段在不同接口中被重复定义。
核心思路：分模块，别贪多
200 个接口不可能一次性全丢进去。直接塞的结果是上下文被撑满，后面的接口质量断崖式下降。
我的做法是按业务模块拆分——用户、订单、支付、商品、物流，每个模块 30-50 个接口，单独一轮生成。每轮控制在 40 个接口以内最稳。
提示词模板是关键。模糊提问拿不到合规的 OpenAPI 3.0 文档。我的系统提示词要求：声明 openapi: 3.0.0；复杂对象提炼到 components/schemas，路径中只用 $ref 引用；必须支持 200、400、401、500 状态码；需要 Token 校验的接口定义 BearerAuth；除 YAML 代码外不输出任何额外解释。
temperature 设 0.3 降低随机性，保证输出规范性。
实际跑通的流程
第一步：提取接口元数据。从 OpenAPI 文件或代码注释中抽取 paths、methods、parameters、schemas。没有 Swagger 注解的话，让 Gemini 直接从源码注释中解析也行。
第二步：组装上下文包。为每个模块准备一个"证据源"——OpenAPI 片段、业务说明、术语表。要求模型基于证据生成，不允许凭空编造字段或枚举值。
第三步：分模块生成。5 个模块，每轮 40 个接口，5 轮跑完。Gemini 3.5 Flash 输出速度 284 tokens/秒，是 GPT-5.5 的近 4 倍。
第四步：自动校验。生成的 YAML 用 Swagger Editor 做结构校验。200 个接口一次性全部通过，没有解析警告。
第五步：人工抽检。抽了 10 个复杂接口让团队核对，修正了 3 处业务语义偏差。这一步不能省——AI 生成的文档"看起来对"但细节可能错。
踩坑记录
坑一：嵌套对象丢失。3 层以上嵌套时，Gemini 偶尔在第二层之后把类型写成 object 但不展开定义。解决办法是提示词里加一句"所有嵌套层级必须完整展开到 components/schemas"。
坑二：错误码凭空编造。它自己编了几个业务错误码，跟实际代码不一致。解决办法是把错误码枚举表作为输入的一部分喂给它。
坑三：流式输出不兼容。流式模式下生成的 YAML 偶尔结构不完整。关掉流式、用同步输出后问题消失。
成本算一笔账
手动写 200 个接口文档，一个人全职干至少两周。用 Gemini 3.5 批量生成，5 轮跑完加人工校验，总共不到 3 小时。
200 个接口生成下来总消耗约 15 万 token，按 Gemini 3.5 Flash 的价格算不到2(citation:1)(citation:4)。如果对格式容错率更高，用DeepSeekV4Flash输出只要2(citation:1)(citation:4)。如果对格式容错率更高，用DeepSeekV4Flash输出只要0.28/百万 token，成本再压一个数量级。但 DeepSeek 在复杂嵌套时的格式稳定性不如 Gemini，偶尔会翻车。
跟纯代码注解方案（SpringDoc/Swagger）比，AI 方案的优势是不需要改现有代码。200 个接口补注解本身就是个大工程。AI 方案适合"先有代码后补文档"的场景。
趋势：API-First 正在成为主流
"代码先行、文档后补"的传统模式正在被淘汰。借助 AI，"API-First"正在成为新的开发流程：架构师用自然语言与 AI 敲定业务边界，一键生成 OpenAPI 规范文档；前端拿文档直接导入 Mock 系统开始联调；后端通过 YAML 逆向生成桩代码。
Gemini 3.5 在格式稳定性、上下文承载、Schema 理解三个维度确实是目前几款模型里最均衡的。但它成本是 DeepSeek V4 的 30 多倍——如果对格式要求没那么严，用 DeepSeek 也够。
拿自己的真实项目跑一遍，比看任何教程都管用。
模型能力以实际测试为准，定价以各厂商最新公告为准。
