上周帮产品同事看一份接口文档，里面写着：user_info 字段返回用户信息，但实际调用时返回的是 userInfo；is_vip 在文档里标了「必填」，结果接口压根不校验——前端写了半天逻辑，上线才发现字段名对不上，状态码也全是 200 堆着，错误信息就一句 {"code":1,"msg":"fail"}。
不是接口难，是文档没规矩
接口文档本质是前后端、测试、产品之间的「合同」。合同里条款模糊，执行起来自然扯皮。很多团队不是不写文档，而是写得随心所欲：有人用 Word 截图贴 Postman，有人在飞书表格里手敲字段，还有的把 Swagger 注释当文档直接交差——结果开发改个字段名忘了同步，测试照着旧文档写用例，上线后三方全卡在数据格式上。
命名：别让下划线和驼峰打架
统一用小驼峰（camelCase）是目前最稳妥的选择。后端 Java/Spring Boot 默认输出 userName，前端 React/Vue 解构也习惯这个风格。如果非要用下划线（snake_case），那就全链路贯彻到底——数据库字段、JSON 返回、文档表格、Mock 数据、甚至错误码里的 key 全部保持一致。
反例：
{
"user_name": "张三",
"is_vip": true,
"create_time": "2024-05-20 10:30:00"
}正例：
{
"userName": "张三",
"isVip": true,
"createTime": "2024-05-20T10:30:00+08:00"
}状态码：别再只用 200 和 500
HTTP 状态码不是摆设。200 表示成功，那「登录失败」该返回 401 还是 400？「订单不存在」是 404 还是业务码封装在 200 里？建议约定：所有业务异常走 4xx（如参数错 400、未授权 401、资源不存在 404），系统级错误才用 5xx；同时配合统一的响应结构：
{
"code": 200,
"message": "success",
"data": { ... }
}其中 code 是业务码（比如 1001 表示「手机号已注册」），HTTP 状态码负责表达通信层语义。
字段说明：光写「字符串」不够，得说清边界
「name：字符串」这种描述等于没写。要注明：长度限制（如 ≤32 字符）、是否允许空（null/empty）、编码要求（UTF-8）、特殊字符是否过滤（比如禁止 <script>）、甚至正则（手机号用 ^1[3-9]\d{9}$）。时间字段更要明确格式：是秒级时间戳？ISO8601 字符串？还是「2024-05-20 10:30:00」这种带空格的本地时间？
文档不是写完就扔，得能跑、能查、能联动
推荐用 OpenAPI 3.0（Swagger/YAPI）维护文档：字段改了，自动生成 Mock 接口供前端联调；加了新状态码，测试能直接导出用例；连 CI 都可以加个检查——提交的代码注释若和 OpenAPI 定义不一致，就拦住合并。文档活起来了，才不会变成项目角落里积灰的 PDF。