用 AI 把接口文档写清楚：从代码注释到可测试示例的三步工作流

【引言】接口文档最常见的失败不是写得少，而是写得“看起来全、跑起来错”：参数名对不上、示例是编造的、错误码只写一半。本文用三步把文档从“文字描述”变成“可测试的契约”，适合给前后端联调、给新人和给 AI 辅助生成做同一套标准。
【一、先定契约，再写文字】第一步不是打开编辑器，而是先列出契约清单：接口路径与方法、鉴权方式、请求参数（必填/可选/类型/取值范围）、响应字段（类型、是否可为空、枚举含义）、错误码与重试语义。做法：从代码里的路由、校验规则和类型定义反推，不要凭记忆手写；发现代码与旧文档不一致时，先改代码注释或校验，再同步文档，避免文档单方面“美化”。
【二、用真实请求生成示例，而不是编示例】第二步用一次真实调用产出示例：准备最小可跑的请求体，记录真实响应，标注哪些字段是动态值（如时间戳、ID、分页游标）。示例必须包含三类：成功示例、典型失败示例（如参数缺失返回 400、鉴权失败返回 401）、边界示例（如空列表、超长分页）。AI 在这里的正确用法是“整理和补全格式”，而不是“凭空编造返回值”；生成后必须把示例在测试环境实际跑一遍，跑不通的示例一律不发布。
【三、按清单自查后再发布】发布前逐项核对：每个必填参数都有类型和示例吗？每个错误码都写了触发条件和处理建议吗？分页、排序、幂等、限流这些容易漏的语义写了吗？最后加一段“联调速查”：一句话说明这个接口是干什么的、一个最小请求示例、一个最常见报错及排查方向。把这段放在文首，能省下大量重复答疑。
【一个最小示例】以查询订单列表为例：请求 GET /orders?page=1&page_size=20，响应包含 items、total、has_more；错误示例：缺少鉴权头返回 401，错误体包含 code 与 message，客户端应提示重新登录而不是重试三次。把“成功、失败、边界”三类示例凑齐，一篇文档才算可用。
【结尾】接口文档的质量标准很简单：新人照着文档第一次调用就能成功，出错时照着错误码一节就能定位。按“定契约、跑示例、清单自查”三步走，文档会从负担变成联调的加速器。