一份API文档的撰写从两天压到四十分钟——我用AI重做了错误码说明这套流程

写在前面：文档为什么总是最后才补

独立开发者和小团队对这件事应该不陌生：接口写完了、功能跑通了，但文档一直空着。等到要给协作方对接、要上架开放平台、要交付客户时，才手忙脚乱地补。更麻烦的是错误码说明——几百个散落在代码各处的错误码，哪些还在用、哪些已经废弃、每个码该返回什么提示，没人说得清。

我最近一次整理一套中型项目的API文档，粗略统计：大约40个接口、120多个错误码。按以前的做法，纯手工整理加撰写，至少要两个整天。这次我把流程交给AI，从抓取到成稿，实际花了不到四十分钟，还不算我中间喝的两杯咖啡。这篇文章复盘整个流程，重点讲清楚：AI在每个环节到底替你做了什么。

用户痛点：文档欠账的三个死结

第一，信息分散。 错误码可能定义在枚举类里、常量文件里、甚至直接硬编码在逻辑分支中。人去逐个核对，费时且极易漏。

第二，写作负担不对称。 写代码有成就感，写文档没有。同样一个接口，实现半小时，写清楚参数说明、调用示例、异常场景，可能要一小时。

第三，更新永远滞后。 接口改了三次，文档还是第一版。对接方拿着过时文档来问，你又得花时间解释。

这三点的共同本质是：文档是高重复、低创造性的工作，恰恰是AI最擅长接管的类型。

AI使用流程：四步走

第一步：让AI收集，不让AI猜

先把相关源码喂给AI：错误码枚举、路由定义、控制器代码。关键指令是「只提取、不推测」。AI会在几十秒内列出所有错误码、触发位置和对应异常类型。这一步替代的是人工翻代码——以前两个小时的活。

第二步：让AI交叉校验

把接口注册文档（如OpenAPI/Swagger导出的JSON）和代码一起给AI，让它比对差异：「代码里存在但文档里缺失的接口有哪些」「错误码在哪些接口中被实际返回」。它能抓出那些你早就忘了的僵尸接口。人工做这个比对，耐心消耗极大；AI做，一分钟出结果。

第三步：按模板批量生成说明

这是核心提效环节。给AI一个固定的说明模板，让它对每个错误码输出统一结构：错误码、含义、触发场景、用户侧提示建议、排查方向。模板固定后，120个错误码的说明是一次性生成的。

第四步：人工抽查收尾

AI生成的内容必须抽查，尤其是触发场景描述是否与实际逻辑一致。我这次的抽查比例约为20%，发现三处描述偏差，改提示词重新生成对应条目即可。这一步不能省——文档是要给别人看的，错一处比漏一处更伤信任。

提示词模板

以下是我沉淀下来的可直接复制的模板：

你是一名API文档工程师。我会提供【错误码定义源码】和【接口代码】两部分内容。

请完成以下任务：

1. 提取所有错误码，输出字段：错误码 / 常量名 / 所在文件与行号 / 触发逻辑（引用代码原文）
2. 对每个错误码，按以下模板撰写说明：
   - 错误码：{{code}}
   - 含义：一句话
   - 触发场景：从代码逻辑推导，注明依据
   - 客户端处理建议：一句话
   - 排查方向：1-3条，面向后端开发者
3. 规则：
   - 只基于提供的代码，不确定的信息标注[待确认]，禁止编造
   - 同一错误码在多个接口出现时，合并触发场景
   - 输出为Markdown表格，附在文末
4. 最后单独列出：代码中定义但从未被返回的错误码（疑似废弃）

这套模板的价值在于「禁止编造」和「标注待确认」两条——它们是让AI输出可直接采用、而不是需要逐条重写的关键。

用AI前后对比

按两个工作日折算，单次节省约13小时。对一个三人的小团队，如果每次版本迭代都维护文档，一年下来节省的时间量级是「周」而非「天」。更重要的隐性收益是：文档维护成本降到足够低之后，它才可能真正保持更新，这才是对接体验的根本改善。

成本方面，处理这个量级的输入输出，一次主流大模型的调用费用通常不到一杯咖啡的钱，具体以官网价格页为准。即便全程用较贵的推理模型，投入产出也完全不成比例。

三个实操提醒

1. 分批投喂。 代码量过大时先按模块拆分，避免上下文溢出导致遗漏。
2. 版本化你的提示词。 模板本身也该进Git，每次微调都记录，团队共用一套标准。
3. AI写初稿，人定口径。 「含义」这一列的措辞建议人工统一，因为它直接面向对接方，风格一致性影响专业感。

写在最后

文档这件事，过去我们欠账不是因为懒，是因为单位时间的产出太低。当AI把这部分成本压到原来的十分之一以下，「没有时间写文档」就不再是借口。如果你的项目涉及对外API调用、模型服务集成或第三方接口对接，把这套流程跑一遍，收益立竿见影。

如果你正在搭建或接入AI相关的服务，需要一个稳定的模型调用入口，可以看看这个平台，注册即可上手体验各类模型的API能力：https://api.thistoken.ai/register

---

想直接跑通示例？访问 https://api.thistoken.ai/register 注册 ThisToken.AI，获取 API Key 后即可开始。