夜雨聆风一个问题：你们团队的接口文档，现在谁在维护？
如果答案是"没人维护"——别紧张，你不是一个人。
我见过的团队，接口文档的状态基本分三种：有 Swagger 但没人看的、有 Wiki 但过期半年的、以及根本没有文档全靠群里问的。第三种最绝，我见过一个支付接口的字段说明，全在某个后端小哥的脑子里。他请假一周，前端全懵了。
为什么接口文档总是"写不好"？不是能力问题，是动力问题
写接口文档难吗？不难。一个接口，写清楚路径、参数、返回值，半小时够了。
那为什么没人写？
因为写文档在开发的工作流里，是"额外工作"。写完代码已经能跑能测了，再花半小时写文档——从个人效率角度看，纯亏。而且代码一改，文档就过期。你改一次，懒得更新；改两次，算了不更了；改三次，这个文档已经废了。
文档烂尾的本质不是不会写，是维护成本太高。
就好像你每天做饭，做完饭洗碗要花 20 分钟。第一天你洗了，第二天你洗了，第三天你想着"明天一起洗吧"。然后水槽里堆了五个碗，你看着它们，决定点外卖。
AI 进来之后，玩法变了
我们团队上个月开始用 AI 自动生成接口文档。不是那种"写完代码再让 AI 补说明"的半自动，是代码提交就触发文档生成，文档和代码绑定在一起。
效果怎么说呢。
之前一个接口从写完到文档上线，平均 30 分钟——写参数说明、写返回值结构、写示例、调格式。现在？ AI 3 分钟搞定。不是"大概搞定"，是真的能用——字段类型、必填标记、枚举值含义，全在。
我拿我们自己的订单模块试了一次。丢给 AI 一段 Controller 代码：
@PostMapping("/order/create")
publicOrderDTOcreate(@RequestBodyCreateOrderRequestrequest){
returnorderService.create(request);
}
AI 生成的文档长这样：
接口名称： 创建订单
请求方式： POST /order/create
Content-Type ： application/json
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | Long | 是 | 用户 ID |
| amount | Integer | 是 | 订单金额（单位：分） |
| payType | String | 是 | 支付方式： ALIPAY / WECHAT / BANK |
| remark | String | 否 | 订单备注，最长 200 字 |
返回示例：
{
"id":10086,
"userId":5521,
"amount":15000,
"status":"PENDING",
"createTime":"2026-04-26T14:30:00"
}
你看，字段 amount 的单位（分）、payType 的枚举值——这些代码里没写但前端必须知道的东西， AI 从上下文和命名里推断出来了。
这比大多数人工写的文档都细。 不是贬义。说实话，很多人写文档就是复制粘贴参数名，连"必填"还是"可选"都懒得标。
我们实际怎么用的（不是"丢给 AI 就完事"）
很多人以为 AI 生成文档就是写完代码让 AI 补一段说明。对，也不对。
我们对 AI 生成文档的使用分三层，越往后价值越大：
第一层：单接口生成（基础）
写完一个 Controller 方法，让 AI 生成文档。这一步解决的是"写文档的时间成本"。
提示词：请根据以下 Spring Boot 接口代码生成完整接口文档。
要求：接口描述清晰、参数说明完整（含必填标记和字段含义）、
返回值结构说明、提供 JSON 示例。
3 分钟出一份文档。复制粘贴到 Wiki 或者你们用的文档平台。
第二层：全项目批量生成（进阶）
这一步才真正解决问题。扫描整个项目的 Controller + DTO + 注解，一次性生成所有接口的文档。
我们团队跑了一次全量生成，大概 200 个接口， AI 用了不到 10 分钟。之前这个工作量，一个人得干两天。
生成完之后做一件事：人工 review 核心接口。支付、退款、对账——这些关键接口的文档，必须有人过一遍。 AI 生成的文档在业务语义上偶尔会偏差，比如把"订单状态"理解成"支付状态"。这种错误必须人工兜底。
第三层： CI 自动更新（终极）
代码提交 → 触发 CI → AI 解析变更的接口 → 自动生成 diff → 更新文档。
这一步我们还在跑，大概跑通了 80%。目前的做法是：每次 PR 合并后， CI 自动检测 Controller 是否有变更，有变更就触发 AI 重新生成对应接口的文档，然后提交一个"文档更新 PR"。
文档终于不再是"额外工作"了，它变成了代码的自动产物。
真实数据（我们跑了一个月）
| 指标 | 之前 | 现在 |
|---|---|---|
| 单接口文档时间 | 30 分钟 | 3 分钟 |
| 前端问接口问题的消息数/天 | ~15 条 | ~4 条 |
| 新人上手一个模块的时间 | 2-3 天 | 1 天左右 |
| 文档与代码一致性 | 低（平均过期 2 周） | 高（代码改文档跟着变） |
前端同事跟我说了一句很实在的话："现在看接口文档，终于不用猜了。"
之前不是没有文档，是文档经常跟代码对不上。前端照着文档调接口，报错了，去群里问，后端说"哦那个字段我们上周改了还没更新文档"。这种事一个月发生四五次，信任就没了。
现在 AI 生成的文档，至少参数类型和结构不会错。业务含义偶尔有偏差，但比"过期两周"强太多了。
最大的坑： AI 不懂业务语义
说个我们踩过的坑。
有一个接口叫 updateOrderStatus，参数里有个 status 字段。 AI 生成的文档写的是：
status: 订单状态（ 0-待处理， 1-处理中， 2-已完成）
看起来没问题对吧？但实际上这个接口的 status 只能传两个值： 1 （处理中）和 3 （已完成）。不能传 0 。
因为"待处理"是订单创建时的默认状态，不是通过 update 接口设置的。
AI 不知道这个业务规则。它从枚举定义里看到了 0/1/2 ，就全写上了。
所以核心接口的文档，必须有人审核。 AI 解决的是"格式和结构"，不是"业务正确性"。这个边界要清楚。
团队落地建议
别一上来就搞全项目。按这个顺序来：
整个过程大概 2-3 周。
最后
接口文档这个问题，从来不是"技术难题"。
它是一个流程问题——文档在你们团队的工作流里，是"额外动作"还是"自动产物"。
AI 的价值就是把这个动作从"手动"变成"自动"。不是写得更好，是写得更多、更新更勤。
这就够了。
你们团队现在接口文档是什么状态？ Swagger ？ Wiki ？还是群里问？评论区聊聊。
