3种方式AI写接口文档,只有一种真能省时间

接口文档是个奇怪的东西。

谁都知道它重要，但写起来没有人喜欢。后端嫌麻烦，前端嫌不全，联调的时候两边对着一份过时的文档吵架。Postman 在 2025 年的调查报告里问了全球 5700 名开发者：最影响 API 协作的问题是什么？55% 的人回答：文档缺口，也就是文档要么没有，要么和代码对不上。

既然 AI 现在这么能写，让它写接口文档不就行了？

我在自己团队里试了三种方式，时间跨度大概三个月。结论先放出来：只有一种方式是真正省时间的，另外两种本质上是在搬砖。

方式一：把代码贴给 AI，让它”理解后生成”

最直觉的方式。把 Controller 或 Handler 函数复制粘贴给 AI，让它直接生成接口文档。

提示词通常长这样：

以下是一个 Java Controller，请帮我生成标准的 API 文档，包含接口地址、请求方式、请求参数、响应示例和错误码说明。[贴代码]

这种方式的确能跑通。AI 看得懂代码，知道你的 POST 路由是 /user/login，知道入参有 username 和 password，也会自动补上 200/400/500 的响应示例。

问题在哪？

问题有两个方向。操作层面：一个中型项目有几十上百个接口，光是”贴”这个动作就会让人崩溃，更别说代码改了还得重新贴。内容层面：AI 看得懂 status 这个字段名，但不知道 status=2 是”审核中”还是”已冻结”。生成的文档格式工整，业务语义一塌糊涂。

我在一个 Spring Boot 项目里统计过：用这种方式处理 40 个接口，加上检查和补充业务说明，前后花了大概两个半小时，比完全手写快了一半，但还不够爽。

这种方式适合一次性存量补全文档，不适合日常开发中的新增和变更。

方式二：接入 Swagger / SpringDoc，让 AI 补充注释

这是很多团队的选择。框架层面，SpringDoc 或 Swagger 可以从注解自动生成文档。AI 的作用变成帮你补全那些注解。

比如你写了一个空接口，让 AI 帮你填 @Operation、@Parameter、@ApiResponse 这些注解，然后 Swagger UI 会自动渲染出文档页面。

@Operation(summary = "用户登录", description = "通过用户名密码获取 JWT Token")@PostMapping("/login")public ApiResult<LoginVO> login(@RequestBody @Valid LoginDTO dto) {    // ...}

这套方案从工具角度看很完善，但在实际使用中发现了两个问题。

第一，注解写在代码里。文档和代码耦合在一起，接口文件会变得很臃肿。我们有几个复杂的接口，注解比业务逻辑还多，维护成本反而上升了。

第二，AI 填注解这件事并不稳定。同一个字段，让它描述十次，能给出七八个不同措辞。团队里几个人各自填，文档风格根本无法统一。我们最后还得专门写一份”注解风格规范”，用来约束 AI 的输出。

这条路适合以 Swagger 为主、规范相对成熟的中大型团队，需要投入一定时间建立文档规范。入门成本不低，但跑稳之后维护成本确实低。

方式三：在 Cursor 里配 Rules，边开发边生成

这是我目前认为效率最高的一种方式。

不让 AI 事后补文档，而是让它在你写代码的时候同步把文档也生成出来。

具体做法是在 Cursor 里配置 .cursorrules（或项目级 Rules），写一条类似这样的规则：

当你生成或修改 API 接口时，必须同步更新 API 文档（docs/api.md）。需要同步的内容包括：- 接口地址和请求方式- 入参和出参结构（含字段说明和示例值）- 业务逻辑说明- 错误码列表

然后把 docs/api.md 作为 Cursor 上下文，每次你让它写一个新接口，它会同时完成代码和文档。

文档不再是代码写完之后的附属品，它和代码同时产出。

9×效率提升——CSDN 博主 Jinkxs（码龄8年）测了这套流程：原来手写一个接口文档需要 180 分钟，用 Cursor Rules 方案压缩到了 15～20 分钟，其中大部分时间花在检查和调试上，AI 自动生成这步只需要 2～3 分钟。

我自己在团队里推这套方案时，最大的阻力不是技术，而是开发者不相信 AI 能维护文档。他们担心 AI 会漏更新、写错字段、描述不准确。这个担心是合理的。

实际运行三个月后的情况：AI 漏更新的概率大约在 10%～15%，字段名几乎不出错，业务描述偶尔需要人工补充。但这比之前”文档从来没更新”的状态强多了。

三种方式的本质区别

区别不只是效率，是文档和代码之间的维护关系。

前两种方式，文档本质上是代码的镜像，代码是主，文档跟着跑。第三种方式，文档和代码是同步产出物，从开发习惯上根本就不允许”文档滞后”这件事发生。

一个容易踩的坑：AI 生成的字段描述太泛

无论哪种方式，AI 在描述业务字段时都会偷懒。

比如一个 type 字段，AI 会写”类型（int）”，但不会写”类型：1=普通用户，2=VIP，3=企业账户”。它不知道你的业务枚举值是什么意思。

解决办法是在 Rules 或 Prompt 里加一条强约束：

对于枚举类型字段，必须列出所有可能的取值及其含义。如果代码中没有注释，在描述中标注"枚举值待补充"。

这样至少能知道哪些字段还缺业务说明，不会悄无声息地漏掉。

怎么推进团队落地

如果你想在团队里推 AI 写接口文档，不建议一上来就搞全套方案。一个相对平滑的路径：

1

用”贴代码”方式给现有项目的核心接口补文档。目的不是补全，是让团队看到 AI 生成的文档”有模有样”，消除抵触。

2

写一份公共文档规范，哪怕只有一页纸：字段描述格式、错误码规范、示例值要求。这份规范是后续 AI 生成的质量基准。

3

在新功能开发中试用 Cursor Rules 方案，限定在一个模块内，跑两周，看实际漏更新多少。

4

根据情况调整 Rules，推广到其他模块。

这个过程大概需要一个月，但比一口气”全团队切换”成功率高得多。

不管选哪种，先把文档写起来再说。文档从来没有最烂，只有更烂。