接口文档怎么写才不被开发骂？这5条编码规范真管用

上周，测试同事老张拿着一份接口文档来找我：‘这文档里 status 字段一会儿是字符串 '0'，一会儿是数字 0，前端调了三次都报错，后端说‘我文档写了啊’——可你写的真是人能看懂的文档吗？’

别让文档成了甩锅现场

接口文档不是写完就交差的‘作业’，而是前后端、测试、产品之间最实际的‘合同’。字段名含糊、状态码没说明、示例数据乱填……这些细节一塌糊涂，上线前扯皮三小时，改接口只要三分钟。

真正落地的5条编码规范

1. 字段命名统一用小写下划线（snake_case）

别混用 camelCase、PascalCase 或中横线。团队一旦约定 snake_case，所有字段就照做：
✅ user_id、order_status、is_deleted
❌ userId、UserId、user-id、User_ID

2. 状态码必须明确含义，禁止裸数字

HTTP 状态码之外，业务 code 要配中文说明。别只写：

{"code": 200, "msg": "success"}

{
  "code": 1000,
  "msg": "操作成功",
  "data": { ... }
}

并在文档表格里注明：

3. 所有字段标注必填/选填 + 类型 + 示例

比如：

{
  "user_name": "张三",     // 必填，string，2~20位中文或字母
  "avatar_url": null,    // 选填，string|null，头像地址，为空表示未上传
  "tags": ["vip", "new"] // 必填，array[string]，至少1项
}

4. 错误响应结构保持一致

无论哪个接口出错，返回格式统一：

{
  "code": 4005,
  "msg": "订单不存在",
  "request_id": "req_abc123xyz"
}

request_id 必须带上，方便日志追踪，别等线上炸了再手动翻 Nginx 日志。

5. 文档更新=代码提交，留痕不留坑

接口改了字段？删了参数？加了校验？文档同步更新，并在变更记录里写清：
• 时间：2024-06-12
• 修改人：王工
• 变更点：删除 old_token 字段，新增 access_token（JWT 格式）
• 影响范围：iOS v2.3+、Web 前端需同步调整

顺手的小习惯，省下大把返工时间

用 Swagger 或 Apifox 自动生成初稿，但别直接交出去——生成器不会告诉你 ‘user_type 字段值为 1 表示企业用户，2 表示个人用户’，这个得你亲手补上；
每次提测前，拉着前端同学一起过一遍文档，边读边调一个真实请求，比写十页说明都有用；
把文档链接放进 Git 提交信息里，比如：feat(api): 更新订单查询接口 /v2/orders — see https://zhiyongtang.com/docs/order-v2。

文档不是越厚越好，是越准越好。别人愿意看你写的文档，不是因为你文笔好，是因为他信你写的每行字都能跑通。