程序员怎么写接口文档：实用技巧分享

别再让同事追着问接口怎么用

在开发过程中，写接口不难，难的是让别人看懂你写的接口。刚入行那会儿，我也觉得只要代码跑通就行，文档随便写两句。结果每次联调，前端同事都得找我问：‘这个字段返回啥？要不要登录？参数错了返回什么？’后来才明白，一份清晰的接口文档，能省下大量沟通成本。

接口文档不是写给自己看的

很多人写文档只写个URL和参数列表，连示例都没有。但你要想，接手的人可能根本不熟悉你的业务逻辑。比如你写了个用户登录接口，光写一个 /api/login 没用，得说明需要传哪些参数，成功返回什么结构，失败时 status code 是多少。

举个实际例子：

POST /api/login

请求参数：
- username: 字符串，必填
- password: 字符串，必填

成功返回（200）：
{
  "code": 0,
  "msg": "success",
  "data": {
    "token": "xxxxx",
    "expire": 3600
  }
}

失败返回（401）：
{
  "code": 401,
  "msg": "用户名或密码错误"
}

这样前端一看就知道怎么处理 token，也不用再打电话问你。

用工具减轻负担

手写文档太累，而且容易过时。推荐用 Swagger（OpenAPI）这类工具，直接在代码里加注解，就能自动生成网页版文档。比如 Spring Boot 项目加上 @ApiOperation 注解，启动后访问 /swagger-ui.html 就能看到所有接口。

数据库相关的接口尤其要注意字段类型和约束。比如你有个订单查询接口，返回字段里有 status，就得注明：0-待支付，1-已支付，2-已取消。不然别人看到数字一脸懵。

保持文档和代码同步

最坑的情况是文档写得好好的，代码改了但文档没更新。新人按文档调用，一直报错。建议把更新文档当成提交代码的一部分，像写注释一样养成习惯。

可以在团队里约定：每次修改接口，必须同步更新 Swagger 注解或者 Markdown 文档。甚至可以写个 CI 检查，发现接口变了但文档没改就报警。

真实场景比理论更重要

写文档时多想想“如果我是前端/测试，我会怎么用”。比如分页查询接口，除了写参数，最好给个真实请求示例：

GET /api/orders?page=1&size=10&status=1

返回：
{
  "list": [...],
  "total": 85,
  "page": 1,
  "size": 10
}

再补充一句：支持按 status 过滤，不传则返回全部。这样比一堆术语解释更直观。

接口文档不是形式主义，它是协作的桥梁。花半小时写清楚，可能帮整个团队节省几个小时的排查时间。别等到上线前才补文档，那时候谁也记不清细节了。