错误码文档越写越糊?先看看你是不是把AI当打字员用了
一、先说三个常见的翻车现场
很多独立开发者和小团队已经尝试过用AI写API文档和错误码说明,但效果往往不理想。常见的失败做法有这么几种:
失败一:把AI当打字员,一次对话生成全部文档。
有人直接丢给AI一句“帮我写这套API的文档”,然后把代码或OpenAPI文件整体粘贴进去。结果得到的是一份看起来工整、实则空洞的文档——每个接口都有“请求参数”“返回示例”,但错误码部分全是编造的,比如凭空出现"10001 参数错误"这种代码表里根本不存在的内容。文档发给用户后,对方按文档排查问题,越查越乱。
失败二:没有错误码的真实上下文,让AI“猜”。
错误码说明是最容易翻车的部分。它需要真实的业务语义:这个码在什么条件下触发、后端会返回什么结构、前端应该怎么提示用户。如果只给AI一个错误码列表,它会生成一堆“万能但无用”的描述——“系统繁忙,请稍后重试”能套用到一半的码上。这种文档写了等于没写,用户看完还是不知道自己错在哪。
失败三:文档写完就冻结,代码更新文档不更新。
AI写文档很快,快到团队误以为这是一次性任务。三个月后接口加了三个错误码、改了两个字段,文档还是初版。用户照着旧文档对接,又踩一遍坑。AI加速了产出,反而让人忽略了“文档是需要维护的活文档”这个事实。
这三个失败有一个共同根源:不是AI不行,而是使用方式把AI的能力压缩成了“文字排版工具”。正确的做法,是把AI当成一个需要被喂足上下文、需要被验证、可以被流程化的协作方。
二、AI能为用户做什么
理清了错误用法,先明确AI在这件事上真正能承担的工作:
- 从代码中提取接口结构:给AI真实的路由定义、Controller代码或OpenAPI/Swagger文件,它能准确提取路径、方法、参数、鉴权方式,不会编造。
- 生成结构化的错误码对照表:只要提供真实的错误码定义(枚举类、常量文件、异常处理代码),AI能生成“错误码—触发条件—返回示例—排查建议”四列表格,这是手写最容易偷懒省掉的部分。
- 补全用户视角的排查指引:AI擅长站在“第一次接入的开发者”视角,为每个错误码写“你可能是哪一步做错了”,比如401是token过期还是格式错误,分别怎么处理。
- 生成可直接运行的请求示例:包括curl、Python、JavaScript多种语言的调用示例,以及对应的成功/失败返回报文。
- 持续维护:代码变更后,把diff丢给AI做增量更新,而不是重新生成全量文档。
三、正确的使用流程
第一步:准备真实材料。 包括OpenAPI文件(或主要接口的路由代码)、错误码定义的源码(枚举或常量文件)、统一异常处理的返回结构、两三个真实的请求/响应报文。这一步决定了文档质量的下限。
第二步:分批喂给AI,先做错误码表。 错误码是最容易出幻觉的部分,必须基于源码生成。让AI输出为Markdown表格,每个码都标注触发条件。
第三步:人工核对,重点查“AI自己加戏”的地方。 对照源码逐一确认错误码是否真实存在、触发条件描述是否准确。发现编造立即删除,并在提示词中明确“只使用我提供的错误码”。
第四步:生成接口文档与示例代码。 用已核对的错误码表作为上下文,再生成接口文档,让返回示例中的错误码引用真实数据。
第五步:建立增量更新习惯。 每次代码变更,把相关的diff和文档片段交给AI做同步修改,并在文档中标注更新日期。
四、可复制的提示词模板
你是一位API文档工程师。请根据我提供的【真实源码材料】生成错误码说明文档。
规则:
1. 只使用我提供的错误码,禁止编造任何不存在的错误码或字段。
2. 如果信息不足,在对应条目标注【待补充】,不要自行脑补。
3. 输出为Markdown表格,包含五列:
错误码 | 错误名称 | 触发条件 | 返回示例(JSON) | 建议排查步骤
4. 返回示例必须符合我给出的统一响应结构。
5. 排查步骤站在首次接入的开发者视角,写具体的检查动作,
例如"检查Authorization头是否携带Bearer前缀",不要写"检查参数"这类空话。
材料如下:
【错误码定义源码】:
{粘贴枚举/常量定义}
【统一异常处理的返回结构】:
{粘贴响应结构代码}
【真实报文示例】:
{粘贴1-2个真实请求响应}
【业务背景一句话说明】:
{例如:面向第三方开发者的支付回调接口}这个模板的关键是第1、2条约束——它们直接针对前文提到的“编造错误码”和“万能废话”两个最常见的失败点。
五、用AI前后的对比
以一个有20个接口、35个错误码的中小型项目为例(这是假设的工作场景,非真实数据):
| 维度 | 手工编写 | 正确使用AI后 |
|---|---|---|
| 首版文档耗时 | 2-3天,经常拖延 | 半天内完成初稿+核对 |
| 错误码说明完整度 | 通常只写码和名称,省略排查建议 | 每个码带触发条件与排查步骤 |
| 多语言调用示例 | 通常只给一种或干脆不写 | curl/Python/JS全覆盖 |
| 代码更新后同步文档 | 靠自觉,经常滞后数月 | diff丢给AI,分钟级完成增量修改 |
| 用户对接咨询量 | 反复解释同样的问题 | 明显减少,文档本身可自查 |
更重要的是质量下限的变化:手工写文档时,最容易省略的恰恰是对用户最有价值的排查指引;而AI在没有成本压力的前提下,会把这部分补齐。人的精力则集中在它最容易出错的地方——核对真实性。
六、几个补充建议
- 模型选择:文档生成对模型要求不高,但错误码核对环节建议用能力较强的模型减少误读源码的情况;不同模型的费用差异较大,以官网价格页为准,按需选择即可。
- 文档生成后做一次“冷读测试”:让AI扮演一个从未见过这套API的开发者,只读文档尝试回答三个典型问题,能暴露文档的盲区。
- 把提示词模板存进团队知识库:让维护文档这件事从“某个人的任务”变成“任何人十分钟就能完成的流程”。
API文档和错误码说明,本质上是产品的一部分。过去它被忽视,是因为写起来枯燥耗时;现在AI把成本压到了很低,剩下的只是养成习惯的问题。如果你的项目正好需要接入大模型能力来辅助这类文档工作流,可以看看 https://api.thistoken.ai/register ,把AI真正用在流程里,而不是当打字员。
---
不想折腾多家供应商的接入差异?在 https://api.thistoken.ai/register 注册,用一个 base_url 调用所有模型。