有次联调,对方问“这个字段是必填吗”,我说文档里写了。打开一看,文档最后更新是半年前。

那天我们靠微信群对了两小时字段。

每个字段四件事

名称、类型、是否必填、取值范围。再加一句示例值,基本就不会有歧义。

嵌套结构要单独列,不要用“同上”省略。

字段类型必填说明
orderIdstring(32)是订单号,雪花 ID
amountint是金额,单位分
statusint是1 待付 / 2 已付 / 3 已取消
remarkstring(200)否备注,超长截断

表 1 接口字段表:四列缺一不可

接口完备率:一个能查的指标

我们把“文档化的字段数 ÷ 实际字段数”作为发布门槛,低于 95% 不允许上线。

这个数由脚本扫描代码里的 DTO 自动比对,不靠人自查。

接口完备率 = 已文档化字段数 ÷ 实际字段数 × 100%含错误码与示例;低于 95% 的接口在 CI 里直接失败。

文档和代码一起改

文档滞后是常态,因为它是“另外一件事”。我们把它塞进同一个提交:改接口必须改文档,否则评审不过。

这一条执行三个月后,完备率从 62% 升到 97%。

1先写契约路径、字段、错误码,评审后冻结2写代码与示例示例请求/响应直接从单测取3CI 校验完备率扫描 DTO 与文档比对,低于 95% 失败4变更同步改字段必须同时改文档,同一次提交
图 1 接口从设计到上线的四步,文档不是最后一步

提示词:找文档和代码的差

我会把 DTO 定义和文档表格一起贴进去,让它对差集。

可直接复制的提示词整段复制
下面是一个接口的 DTO 定义与现有文档字段表。请:
1. 找出代码中存在但文档缺失的字段;
2. 找出文档中存在但代码已删除的字段;
3. 检查必填标记与代码校验注解是否一致;
4. 指出缺少取值范围说明的枚举字段;
输出表格:字段 / 问题类型 / 建议补充。不要重写文档。

文档不是写给新人的,是写给三个月后的自己。

那时候你一定不记得 remark 字段为什么限 200 字。