第83篇:用 AI 写 API 文档/接口说明——对接方一看就懂

接口写完了，对方问了你 27 个问题。

你花两天写完一组接口，发消息给前端同事："接口好了，你对接吧。"然后噩梦开始——对方连珠炮似的问：地址是啥？这字段传字符串还是数字？不传会怎样？返回的 status 有几种值？我传错了报 500 是谁的问题？能给我个例子吗？

一个下午过去，你的代码一行没写，全在回消息。 更惨的是三个月后换新人对接同一接口，同样的 27 个问题你再答一遍，而且这次你自己都忘了 type=3 是啥意思。

这就是没有接口文档的代价：你不是在写代码，你在做人肉客服。

好消息是这事特别适合交给 AI——接口文档 90% 是结构化搬运，AI 又快又整齐。这一篇把"写文档"从两小时苦差变成十分钟顺手活。

一、先想清楚：对接方到底想知道什么

对接方只关心五件事，一件不多一件不少：

记住五个字：址、入、出、错、例。 五样齐了，对接方基本不来问你；少任何一样，问题就以消息形式回到你身上。其中**「错」和「例」是新手最易漏、也最救命的两样**。

二、AI 写文档四步法：喂、补、生、验

第一步：喂——把原料给 AI

三种喂法任选：

• 喂代码（最准，整段路由+校验+返回）
• 喂请求样例（最省事，一次真实请求和返回）
• 喂大白话（应急，口述"查订单列表，传用户 id 和页码，返回订单数组"）

推荐组合拳：代码 + 一次真实返回。 ⚠️ 贴真实返回前，先把手机号、身份证、密码、真名换成假数据——这是底线。

第二步：补——补上 AI 猜不出来的三样（最关键，90% 的人跳过）

AI 看代码能推出字段名和类型，但有三类它永远猜不出：

• ① 业务含义：代码写 type 是数字，AI 只能写"类型"，只有你知道 1=普通，2=预售，3=团购。
• ② 边界规则：分页每页最多传多少？名字最长几字？藏在你脑子里。
• ③ 历史的坑：比如"这字段叫 name 但存的是昵称""重复调用不报错也不重复扣款"——一条省对方半天。

正确做法：让 AI 先问你，而不是直接写。

第三步：生——指定格式，别让它自由发挥

不指定格式 AI 给你一坨散文，必须明确要求用表格，至少包含这五块：

• 接口概览（名称/地址/方式）
• 请求参数表（字段/类型/必填/说明/示例）
• 返回参数表
• 错误码表
• 完整请求+返回示例

小技巧：直接说"用 Markdown 表格输出，我要直接粘到文档工具里"。

第四步：验——照着文档调一次（分水岭）

文档生成完，你按示例一字不改调一次接口：调通了→文档对；调不通→99% 是文档错，不是接口错。新手最容易文档看一眼觉得挺像样就发对方，结果对方第一步就挂——你没省事还赔了信任。验证三分钟，决定这份文档是资产还是垃圾。

三、错误码：三要素缺一不可

菜鸟写的错误码表：400 参数错误、500 服务器错误——对方看完还是懵：到底哪个参数错？怎么改？

合格错误码必须有三要素：

带「境」和「办」的错误码表，能让对方自己把异常分支写完，不用问你。⚠️ AI 这里最容易偷懒：只写代码里明确 return 的错误，漏掉参数校验失败、权限不足、限流、超时这些"隐形错误"——生成完自己对着这四类过一遍。

四、示例部分：真实数据 > 占位符

AI 默认给你 { "name": "string", "age": 0 } 这种——对方看完还是问 createTime 到底是日期还是时间戳。好的示例用真实格式的假数据："name": "张三", "age": 28, "createTime": "2026-08-06 15:30:00"，一眼知道格式，零提问。提示词里加一句："示例值全用符合真实格式的假数据，禁止 string/0 这类占位符，时间字段写完整格式。"

五、三个必踩的坑（提前躲开）

坑 1：AI 会编字段。 代码 8 个字段，它写 10 个——多出的 status、remark 是对方照着传、接口直接不认的。躲法：生成后拿文档字段表和代码逐个对，多的删少的补，两分钟省对方两小时。

坑 2：AI 把"可选"写成"必填"。 它倾向全标必填因为"更安全"，结果对方每次传一堆没用参数。躲法：必填/可选这列自己过一遍，别信 AI。

坑 3：文档和代码分家，三个月后全烂。 文档在在线文档、代码在仓库，改了代码没人改文档，半年后过时文档变凶器——过时的文档比没有文档更害人。躲法（选一条）：就近原则（文档以注释写在接口代码上方，改代码顺手改）或重生成原则（改完把同一提示词再跑一遍，整段替换，因提示词已存好，重跑一分钟）。

一句话：文档不是写一次的事，是每次改接口顺手做的事。

六、进阶一步：让文档能直接被工具吃掉

如果团队用了接口调试工具（Apifox、Postman、Swagger 之类），让 AI 直接生成能导入的格式，省掉手工录入。提示词加一句："同时输出一份 OpenAPI 3.0 格式的 JSON，我要直接导入接口工具。" 对接方点一下导入，接口列表全出来还能直接发测试。你不用看懂那份 JSON——工具看得懂就行。

📦 提示词模板盒子

模板 1：先问后写（推荐首选）

你是一个 API 文档专家。我要为下面这个接口写对接文档，读者是前端/第三方对接方。
【粘贴接口代码，或一次真实请求+返回】
请先别写文档。先扮演从没见过这接口的对接方，向我提 5-8 个必须知道、但从代码看不出的问题（重点：字段业务含义、取值范围、边界规则、失败情况）。一次列全，我统一回答，然后你再写文档。

模板 2：正式生成文档

根据代码和我刚才的回答，输出完整接口文档，用 Markdown 表格，必须含五部分：
1.接口概览：名称、地址、方式、用途一句话
2.请求参数表：字段名|类型|是否必填|说明|示例值
3.返回参数表：字段名|类型|说明|示例值
4.错误码表：错误码|触发场景|对接方怎么处理
5.完整示例：一个请求+一个成功返回+一个失败返回
要求：示例全用真实格式假数据，禁 string/0 占位符，时间写完整格式；只写代码里真实存在的字段，不推测补充；不确定的标【待确认】，不编造。

模板 3：专门补全错误码

针对这个接口，把所有可能失败的情况列全，不要只列代码里显式返回的。必须覆盖四类：参数校验失败、权限不足、资源不存在、系统异常（超时/限流）。
每一条按三列输出：错误码 | 什么情况出现（具体到字段和条件）| 对接方怎么处理（给用户什么提示、要不要重试）
某类当前代码没处理的，单独指出并标"当前未处理，建议补充"。

模板 4：改完接口后刷新文档

这是我改动后的接口代码：【粘贴新代码】
这是原来的接口文档：【粘贴旧文档】
请对比后输出：1.变更清单（新增/删除/含义或必填变化）2.会不会影响已在用的对接方？会的话明确指出哪条是破坏性变更 3.更新后的完整文档（保留旧文档里我手工补充的业务说明）

模板 5：生成可导入的接口工具格式

把上面这份接口文档，同时输出一份 OpenAPI3.0 规范的 JSON，字段、类型、必填标记、示例值、错误响应都与文档完全一致，我要直接导入接口调试工具。只输出 JSON，不要额外解释。

八、一页纸速查表

结语：文档不是写给领导看的

很多人把写文档当"应付检查"，所以又长又空。真正的验收标准只有一条：对接方看完文档，能自己把活干完，不来问你一句。 达到，写十行也是好文档；达不到，写十页也是废纸。

AI 最大的价值，是把你脑子里零散、说得清但懒得写的东西，五分钟变成整整齐齐的表格。你只需做两件它做不了的事：补业务含义，验一遍真假。

到这里，「重构与质量」小节的七个实操话题讲完：重构、优化、单测、Code Review、注释、代码风格、API 文档。

下篇预告

第84篇：质量类小结——质量保障清单。 七篇学下来你手里有一堆方法论，但明天上班先做哪个？下一篇把这七篇收敛成一条质量时间轴 + 一张一页纸清单，点名五个新手最容易踩的质量误区（"质量是最后检查出来的"排第一），以及用 AI 做质量把控绝不能破的三条铁律。