我用 AI 给项目写 API 文档，然后发现它比我自己写的好看多了
上周我在做一个内部服务的版本升级，改完了十几个接口，站在文档更新的边缘犹豫了五分钟，然后把任务甩给了 AI。
不是第一次这么干了。但这次我决定认真记录整个过程——不只是”有没有用”，而是”好在哪、烂在哪、下次怎么做”。
背景：我们的文档一直是个烂摊子
坦白说，我们团队的 API 文档维护状态属于”大家都知道烂、大家都没心情修”。
Swagger 的 UI 倒是开着，但注释有一半是早年前端同事贴上去的，内容对不上现在的接口；有些接口改了参数类型、换了返回结构，文档里一个字没动。最离谱的是有一个 /api/v2/order/detail，响应体里的字段注释是”不知道干嘛的”——这是原文，不是我编的。
所以这次升级顺带处理了一下文档问题，用 AI 跑了一轮自动生成和整理。
我用的是什么方式
主要工具是 Claude Code，辅助用了 Python 写的一个简单解析脚本。
我们是 Python FastAPI 的后端，接口是用 Pydantic 模型定义的，这给 AI 读代码提供了很好的结构——类型信息完整，字段基本都有，部分有 description。
流程大概是这样：
先让 Claude Code 扫描整个 api/ 目录，把所有路由和对应的 Request / Response 模型提取出来，整理成一个中间格式（JSON）。这一步我没有完全自动化，而是让它生成之后我手动过了一遍，主要是确认有没有遗漏和识别错误的接口。
接着把这份中间格式喂给第二个任务：生成 Markdown 格式的 API 文档。让它按照”接口描述 → 请求参数 → 响应结构 → 示例”的格式输出。
最后是一轮人工校对。
它做得好的部分
先说好的，因为确实比我预期的强。
类型和字段的整理明显比我自己写快。 一个接口有七八个请求参数、十几个响应字段，我自己写要花十到十五分钟。AI 扫完生成初稿大概三十秒。准确率大概在 90% 左右，剩下 10% 是业务含义没说对，技术结构基本没错。
格式统一这件事做得特别好。 我以前手写文档最大的问题是写着写着风格就飘了——有时候参数说明写成”用户ID，必填”，有时候写成”the user’s unique identifier (required)”，有时候又是”传用户的id”。AI 输出的格式从第一页到最后一页基本一致，这件事人工做起来反而费劲。
示例生成超出预期。 我让它顺带生成请求和响应的 JSON 示例，它给出的示例不是随机填充的数字字符串，而是根据字段名猜了合理的值——user_id 给的是 10086，order_status 给的是 "paid"，不是 "string123"。这让文档读起来比我印象里的 AI 生成内容顺很多。
它踩的坑和我发现的问题
然后说坑，这是我觉得更值得记录的部分。
业务语义是 AI 的盲点。 技术结构它看得懂，但业务含义它只能猜。我们有一个字段叫 is_locked，AI 生成的描述是”锁定状态，布尔值”——没错，但缺了一半：这个字段在我们系统里专门指”资金锁定”，和普通的”账号锁定”是两回事，很多下游系统调用时会搞混。这类业务上下文的注释，AI 补不出来，只能人工加。
有几个接口的描述”看起来对但用起来错”。 有一个接口的 start_time 参数，AI 描述为”查询开始时间，Unix timestamp”。但实际上我们内部规范是传 ISO 8601 字符串，不是时间戳——这个信息没有写在代码注释里，AI 从参数名猜，猜错了。这种错误如果不细看会直接流传下去。
循环依赖的模型处理得不干净。 我们有几个嵌套引用比较复杂的 Response 模型，AI 处理时出现了重复展开的情况，同一个子模型在文档里出现了三次。不影响理解，但看起来很乱。后来让它改用 $ref 引用方式，好了很多，但这个调整需要人工介入。
最后的文档质量怎么样
说实话，比我之前手写的好看。
不是因为 AI 写得多厉害，而是它真的做到了我懒得做的事：格式统一、示例完整、每个字段都有说明（即使说明不一定准确）。这三件事加在一起，读起来就比以前的文档专业不少。
我自己手写的文档往往是”这个我觉得大家都懂就不写了”，结果三个月后自己都想不起来了。AI 不会觉得有什么是”大家都懂的”，它把能写的都写了。
整体来说，这一轮 AI 生成节省了大概 70% 的时间，剩下 30% 花在校对和补充业务语义上。对我来说这是一个合理的分工——技术结构的体力活交给它，业务判断留给我。
现在我的新工作流
做完这次实验之后，我把 AI 辅助文档更新加入了接口修改的 checklist：
改完接口之后，先让 Claude Code 扫一遍变更的文件，生成”变更摘要”——哪些接口改了、改了什么。这一步基本准确。
然后让它基于变更摘要更新对应的文档段落，我再做一轮业务层面的 review，主要补字段的业务含义。
这个流程比”改完代码然后手动更新文档”省事多了，主要是打破了”文档更新是额外工作”的心态——当 AI 把体力活都做了，剩下那点业务校对反而不怎么抵触了。
不过有一件事我还没解决：怎么让 AI 意识到哪些字段的说明可能过时了。现在它还不会主动提示”这个描述和代码对不上”，只会老实地把代码里的东西翻译一遍。也许这是下一步可以折腾的方向。
如果你也在维护一个文档欠债很深的项目，可以从一个模块试起来，感受差异比看我的描述直观得多。