三天变三小时 - 我把API文档和错误码表全交给AI重写了一遍
一个大多数开发者都心照不宣的事实
API写完了，文档还没写。这不是懒惰，是结构性的问题：
- 写代码时有心流，写文档时只有折磨
- 错误码散落在代码各处，谁也说不清一共定义了多少个
- 文档写了第一版之后，代码改了三轮，文档还停在 v0.1
- 用户报错时来问“这个 40302 是什么意思”，你自己也要去翻代码
我在一个小团队负责过两年API维护。每次版本发布前的“补文档”环节，平均要占用 6-8 小时，而且产出的文档质量与耗费的时间严重不成正比——错误码表经常漏掉新加的码，参数说明靠复制粘贴上一个参数的描述改两个字。
直到我试着把这件事交给AI。下面是完整的实践过程和量化对比。
AI能在这件事上做什么
先说结论，AI在API文档场景里能承担四类工作：
1. 从代码和注释抽取接口定义。 把 controller、handler 的代码片段贴给AI，它能整理出标准化的接口说明：请求方法、路径、参数名、类型、必填性、示例值。
2. 错误码汇总与去重。 把散落的错误码定义（常量文件、枚举、异常类）交给AI，让它输出一张“码—含义—触发条件—用户该怎么办”的表格，并标出疑似重复或语义冲突的码。
3. 面向不同读者改写。 同一个接口，给前端同事看的和给第三方接入方看的详略程度完全不同。AI可以基于同一份底稿生成两个版本。
4. 排查“文档债”。 让AI比对旧文档与新代码，列出已经过时的参数、缺失的说明、前后矛盾的描述。
这四件事的共同点：机械、重复、需要跨文件信息整合——正是人做得慢、AI做得快的那类工作。
我的实际使用流程
整个过程分四步，一个下午完成：
第一步：收集原料（约40分钟）。 导出所有接口的代码定义、错误码枚举、现有的旧文档。不需要整理格式，AI对格式混乱的输入容忍度很高。
第二步：生成接口文档初稿（约30分钟）。 分批把代码贴给AI，每批不超过10个接口，避免长上下文导致的遗漏。
第三步：生成错误码总表（约20分钟）。 单独一轮，重点让AI做去重和冲突检测——这一步人工做最容易出错。
第四步：人工校对（约1.5小时）。 检查AI编造的默认值、不确定的参数含义。这一步不能省，AI偶尔会“合理地猜”一个你没写过的默认参数。
前后对比：效率视角
以一个中等规模的API项目（约40个接口、130个错误码）为参照：
| 环节 | 纯人工 | AI辅助 |
|---|---|---|
| 接口文档撰写 | 约12小时 | 约2小时 |
| 错误码表整理 | 约6小时 | 约1小时 |
| 版本更新时的文档同步 | 每次3-4小时 | 每次约40分钟 |
| 文档质量 | 漏项常见，风格不一 | 结构统一，需抽查校对 |
按一个月两次版本迭代计算，文档维护从每月约 8 小时降到 1.5 小时。对小团队来说，这相当于每月找回一个完整工作日。而使用AI工具的API调用成本，相比节省下来的人力时间，几乎可以忽略——具体以官网价格页为准。
更重要的是质量的隐性提升：错误码表第一次做到了“全量、去重、每个码都有用户视角的处理建议”，接入方的咨询量肉眼可见地下降了。
可复制的提示词模板
这是我反复调试后固定下来的模板，直接替换占位符即可用：
你是一位资深API文档工程师。请根据我提供的代码，生成规范的API文档。
【输入材料】
<粘贴接口代码 / 错误码定义 / 相关注释>
【输出要求】
1. 每个接口包含：接口名称、请求方法与路径、功能说明、
请求参数表（参数名/类型/必填/说明/示例值）、
响应字段说明、一个完整请求与响应示例
2. 错误码整理为表格：错误码 / 含义 / 触发条件 / 用户处理建议
3. 标记出以下问题（如有）：
- 疑似重复或语义冲突的错误码
- 代码中存在但注释缺失的参数
- 你不确定而做了推测的地方，用【待确认】标注
4. 语言风格：面向第三方开发者，简洁、准确，不用营销化措辞
5. 不要编造代码中不存在的信息；推测必须显式标注
【目标读者】<内部同事 / 第三方接入方>第3条和第5条是关键：强制AI暴露不确定性，把“看起来很可信的编造”变成“明确标注的待确认项”，人工校对的效率会高很多。
几条踩坑经验
- 分批投喂。 一次塞50个接口，后半段的参数表会开始敷衍。10个左右一批效果最稳。
- 错误码单独一轮。 和接口文档混在一起生成时，错误码表更容易遗漏。
- 保留AI的原始输出做diff。 下次版本更新时，直接让AI对比新旧两版输出，变更点一目了然。
- 人工校对不可跳过。 AI最多帮你完成80%，剩下20%的准确性判断只有你能负责——但20%的时间远少于100%。
写在最后
文档这件事的特殊之处在于：所有人都知道该做，所有人都拖着不做，因为投入产出比太差。AI把这个比例彻底扭转了——当维护文档的成本从“半天”降到“半小时”，它就从负担变成了习惯。
如果你的项目正好也在接大模型能力、需要一个稳定的API网关和模型服务，可以看看这个平台，注册入口在这里：https://api.thistoken.ai/register
---
想直接跑通示例？访问 https://api.thistoken.ai/register 注册 ThisToken.AI，获取 API Key 后即可开始。