上周帮朋友公司改一个老项目，前端同事发来截图：一行红色报错，下面跟着三个问号——‘这个字段到底要不要传？返回的 code 是 0 还是 1？错误信息在哪看？’
接口文档不是写给机器看的
很多人把接口文档当任务交差：Swagger 自动生成、字段列全、状态码写上就完事。结果呢？前端调用时卡在‘我该传空字符串还是 null’，测试同学翻着文档反复问‘这个字段是必填还是可选？’
真实场景里，一份能用的后端接口文档，得让没看过代码的人，5 分钟内能跑通第一个请求。
少点字段列表，多点使用场景
比如用户登录接口，别只写：
POST /api/v1/login
Request Body:
{"username":"string","password":"string"}换成这样更管用：
## 场景1：正常登录
POST /api/v1/login
{"username":"zhangsan","password":"123456"}
→ 返回 200，body 含 token 和 user_id
## 场景2：密码错误
POST /api/v1/login
{"username":"zhangsan","password":"wrong"}
→ 返回 401，body：{"code":1002,"msg":"密码错误"}状态码不能只写‘200 成功’
HTTP 状态码只是骨架，真正要命的是业务状态。我们有个订单接口，前端总收不到“库存不足”的提示，后来发现文档里只写了‘200 返回成功数据’，但实际库存不足时也返回 200，靠 body 里的 code 字段区分——这个必须写进示例和说明里，而不是藏在备注小字里。
建议每类错误都配一个 curl 示例：
curl -X POST http://localhost:8080/api/order \
-H "Content-Type: application/json" \
-d '{"item_id":999,"count":100}'
# 响应：
{"code":2001,"msg":"库存只剩 5 件","data":null}别忘了“怎么测”
上线前最常被问的问题是：“我怎么本地验证这个接口？” 文档末尾加一小节‘调试提示’很实用：
• 测试账号：testuser / 123456（已预充值）
• 沙箱环境地址：https://staging-api.shiyongkeji.com
• Token 获取方式：先调 /auth/login，再在 Header 加 Authorization: Bearer xxx
有次我们漏写了沙箱环境的限流规则，前端在测试时疯狂重试导致被封 IP，最后发现文档里连“每分钟最多调 30 次”都没提。
接口文档不是越厚越好，而是越容易被打开、被找到、被用对，越好。