后端服务接口文档怎么写才不被前端骂？

上周组里又因为一个接口字段没写清楚，前端同事在群里发了个‘？？？’截图，后面跟了三个叹号。不是没写文档，是写了但像谜语——比如只写‘返回结果’，没说结构、没标必选、没列枚举值，连状态码都靠猜。

接口文档不是备忘录，是契约

很多人把接口文档当成写完代码顺手记两笔的备忘录：字段名、类型、大概意思。可现实是，前端调用时它就是唯一依据。字段少传一个，500；多传一个，400；时间戳传了字符串，页面直接白屏。这不是bug，是契约没签清楚。

一份能跑通的文档，至少得有这四块

1. 请求路径 + 方法
别只写 /api/v1/user，得标清是 GET 还是 POST，带不带 query 参数，path 里有没有动态 ID：

GET /api/v1/users?offset=0&limit=20

2. 请求体（POST/PUT）或 Query 参数
每个字段标清楚：名称、类型（string/int/boolean）、是否必填、示例值、约束（如“长度≤32”“仅支持 email 格式”）。别写“参数见代码”，代码会变，文档才是基准。

3. 成功响应结构
用 JSON 示例，字段对齐实际返回，嵌套层级别省略。比如用户列表，不能只写“返回用户数组”，要写成：

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 123,
        "name": "张三",
        "status": "active",
        "created_at": "2024-06-15T09:22:10+08:00"
      }
    ],
    "total": 1
  }
}

4. 错误码和含义
除了 200 和 500，得列清楚业务错误：401（token 过期）、403（权限不足）、404（资源不存在）、422（参数校验失败）……每条配一句话说明，最好加一句“前端应如何处理”，比如“422 时读取 response.data.errors 显示表单红字”。

顺手几个小习惯，省下大把联调时间

• 接口变更第一时间同步文档，哪怕只是改个字段名——别等前端问了再补；
• 用 Swagger 或 Apifox 生成在线文档，支持试调、自动同步；
• 在文档顶部加个「最后更新时间」和「负责人」，谁写的谁兜底；
• 给测试环境单独开个文档页，标清楚 base_url 是 https://test-api.zhiyitong.com，别让前端自己切环境瞎试。

文档不是给领导看的汇报材料，是每天真实流进前端代码里的数据说明书。写清楚，就是少一次深夜钉钉语音，少一个线上报错，少一句“你那边改下吧，我这边不好动”。