用 AI 从代码生成 API 文档，正确的做法不是让它”写一份文档”，而是拆成三段：注释写意图、 OpenAPI 写契约、示例代码写可用性。缺任何一段，生成的文档都会在两周内失效——注释缺失导致描述空泛，契约缺失导致字段对不上，示例缺失导致调用方照样跑不通。
为什么”一键生成文档”多半是烂的
多数人失败的原因不是模型不行，而是把三种性质完全不同的信息混在一起要。文档里其实有三种东西：
- 意图：这个函数为什么存在、什么情况下不该用它。代码里没有，只能从上下文推断，模型擅长补全但不擅长凭空编造。
- 契约：路径、参数、返回结构、错误码。代码里有，但散落在路由、校验 schema 、中间件三处，必须让模型读全才能提准。
- 示例：能跑通的最小调用。代码里通常没有，需要模型生成后再验证。
把这三件事塞进一句”帮我写文档”，模型只能挑它最有把握的部分写，结果通常是：契约写得还行，意图全是套话，示例是编的。
三段式：一段一段喂，别一次要完
第一段：注释只写”为什么”
注释这一层的产出目标是 TSDoc / JSDoc，不是散文。给模型的指令要带明确约束：
- 为导出函数补
@param，写清单位与取值范围（代码里已经校验的就直接引用校验条件）。 - 补
@throws。这一条是生成式文档强于手写的地方——模型会顺着调用链找到被重新抛出的异常，人写的时候经常漏。 - 行内注释只在逻辑不明显的地方加。解释”这行做了什么”的注释是噪音，解释”为什么这么做”才有价值，这条要写进指令里，否则模型会把每行都注释一遍。
- 注释长度不超过函数体。这是防止 AI 过度解释最便宜的一条约束。
第二段：OpenAPI 从路由与校验 schema 提取
不要让它”根据我的 API 写一份 OpenAPI”。要指定输入源：路由处理器 + 校验 schema + 中间件这三者一起读，才拿得到完整的请求体结构、认证要求与限流响应头。
实践里最有效的顺序是：先让它输出一份完整的 openapi.yaml，再用 lint 工具（如 Redocly）跑一遍，把报错丢回给它修。这个循环比反复改提示词有效得多，因为语法错误是确定的、可枚举的。
更新已有文档时，一定要在指令里写明保留已有的人工描述。否则每次重新生成，上一次手写的业务背景就被冲掉了，几轮之后文档会退化成纯字段表。
第三段：示例代码必须验证过才入档
每个接口给一段最小可运行示例，要求包含：认证头的写法、必填参数、一次成功的响应体。生成之后必须真的跑一次——这是唯一能证伪的环节。
内部接口觉得 OpenAPI 太重时，可以退到 Markdown 参考：方法、路径、参数、请求示例、响应示例五段式，够用且好维护。
防漂移：把校验做成闸门，而不是靠自觉
生成一次不难，难的是三个月后还对得上。三道闸门成本都不高：
- 文档检查脚本：TypeDoc 开
--validation.notDocumented且把警告当错误，OpenAPI 走 lint，两条都进docs:check。 - 契约测试：比对 spec 里的路径与代码里实际注册的路由，两边对不上就失败。这条能抓住”接口加了但没写文档”和”文档里有但已删除”两种情况。
- CI 漂移检查：用无头模式跑一次对比任务，输出结构化 JSON 让流水线判断。它不自动改，只负责报警。
配合编辑钩子，在改到路由文件时自动提示”记得更新 openapi.yaml”，能把大部分漂移挡在提交之前。
一个可用的提交前提示钩子
.claude/settings.json 里配一条 PostToolUse 钩子，匹配 Edit|Write，当被改动的文件路径落在路由目录时输出一条提醒：路由文件已变更，若接口契约有变化请同步更新文档。钩子只能提醒，不要让它自动改文档——自动改出来的 diff 没人 review，等于没改。哪些文档别让 AI 独写
有一条分界线很清楚：答案在代码里的，让 AI 生成；答案在人脑子里的，只让它起草。
- 可以生成：TSDoc/JSDoc 、 OpenAPI spec 、 README 的安装与启动段、 CHANGELOG 初稿、架构文档（要求引用真实文件路径）。
- 只能起草：架构决策记录（ADR）、变更说明里的”为什么”。问模型”这个模块为什么用队列”，它会给出一个听起来很合理的理由，无论真实原因是否存在。这类必须人来写或至少由决策人签字。
- 先把校验闸门加进仓库：装好文档检查依赖，加一条
docs:check脚本，跑一次拿到失败清单——这份清单就是要补的文档 backlog 。 - 按目录分批补注释，一次一个目录。每个目录单独一轮，diff 小到能逐条看，跑一次
docs:check确认收敛。 - 让它读路由处理器与校验 schema 生成 OpenAPI 初稿，用 lint 报错驱动修正循环，直到零报错。
- 为每个接口补最小可运行示例，逐个实际执行验证，跑不通的改到能跑为止。
- 把文档改动与代码改动放进同一个 PR 评审，并开启 CI 漂移检查。
文档准不准，和上下文质量直接相关
生成不准确，八成是它没读到该读的文件。路由散在多个目录、校验 schema 在另一个包里、认证逻辑在中间件里——这些情况下先解决检索问题再谈生成。我们在 AI 编程的代码检索怎么做 里讲过符号索引与依赖切片的做法，这里同样适用。
另外，生成的接口文档会暴露参数与返回结构，评审时顺带过一遍安全视角，别把内部字段名或调试用的宽松校验写进公开文档，相关检查项可以参考 AI 生成代码怎么过安全审计。
AI 生成的 API 文档能直接对外发布吗
每次改代码都重新生成会不会把人工描述冲掉
小项目有必要上 OpenAPI 吗
为什么生成的示例代码经常跑不通
小结
把文档生成拆成”注释写意图、 OpenAPI 写契约、示例写可用性”三段之后，AI 的角色就从”代笔”变成”提取器”——它负责从代码里把已存在的事实抽出来，人负责补代码里没有的判断。这样分工出来的文档，才有可能在三个月后依然对得上。
延伸阅读：Claude Code Skills 用法详解讲的是怎么把这套流程固化成可复用的技能文件；AI 编程怎么利用运行时信息则介绍了把真实报错喂回模型的定位闭环，和文档校验是同一类思路。
评论 (0)