为什么接口文档总是写不好？
刚接手一个项目，想看看某个接口怎么用，结果打开文档发现字段说明只有“用户ID”，连类型都没写。你是不是也遇到过这种情况？接口文档写得模糊，前端查半天，测试反复确认，最后锅还甩给后端——“你文档没写清楚”。
好文档不是写给机器看的，是给人用的
别把接口文档当成应付检查的作业。它本质上是一份沟通工具，目标是让对接的人快速理解、少走弯路。比如你写了个用户登录接口，除了路径和方法，还得说清楚：哪些字段必填？错误码代表什么？有没有频率限制？
核心信息不能少
每个接口至少包含这几个部分：请求地址、请求方法、请求参数、返回结构、错误示例。拿获取订单列表来说：
GET /api/orders?page=1&size=10
响应成功：
{
"code": 0,
"msg": "ok",
"data": {
"list": [
{ "id": 123, "amount": 99.5, "status": "paid" }
],
"total": 1
}
}
错误情况（未登录）：
{
"code": 401,
"msg": "请先登录"
}字段别偷懒，每个都加注释。比如 status 的取值范围是 created, paid, shipped, closed，这些必须写明白，不然前端展示状态时全靠猜。
用工具减轻负担
手动维护 Markdown 文档容易不同步。可以试试 Swagger（OpenAPI）这类工具，代码里加点注解，文档自动生成。Spring Boot 项目配个 @ApiOperation 注解，启动后就能看到可视化页面，前端同事直接点着试。
别忘了版本和变更记录
上线三个月后要改个字段，老接口还得兼容。这时候文档里得标明 v1 和 v2 的区别。比如 v2 把 user_name 换成 full_name，就得在文档顶部加个变更日志，避免别人踩坑。
实际场景中的小细节
有一次团队接入支付回调，文档里没写签名验证方式，结果第三方按 MD5 算，我们用了 SHA256，来回折腾两天。后来才意识到，加密逻辑、时间戳格式这种看似“常识”的东西，恰恰最需要写进文档。
还有就是测试环境地址、示例 Token、模拟数据构造方法，这些虽然不算接口本身，但能极大提升对接效率。与其等别人来问，不如提前写在文档开头。
写文档也是写代码一样，需要迭代
没人一开始就能写出完美的文档。每次联调遇到问题，回头补一条说明，久而久之就越来越清晰。关键是别等到最后才补，边开发边更新，负担最小。
好的接口文档，能让新成员半小时内跑通第一个请求，能让跨组协作减少一半沟通成本。它不是附加任务，而是开发流程中自然的一部分。