做开发的人都懂,写接口文档时要么太简略,联调时反复“找补”;要么太冗余,没人愿意看。其实只要抓住规范核心,再套对模板,就能轻松搞定。

很多人写接口文档容易走极端,要么只有“地址+参数”,要么把代码注释全搬上去。合格的接口文档本质是“联调说明书”:要让前端、测试、甚至跨团队的开发者,不用问你,就能独立完成对接。核心要做到三点:信息全、逻辑清、易维护。
接口文档的模块不能乱,要符合开发者的阅读逻辑。开头先写接口说明,比如“用户登录接口”,再写接口地址(注意区分测试/正式环境)、请求方式(GET/POST等)。接下来是参数部分,要分“请求参数”和“响应参数”,每个参数都要标清楚:名称、类型、是否必填、示例值、说明。比如请求参数里的“phone”,要写清是字符串类型、必填、示例是“13800138000”、说明是“用户手机号”。最后别忘了加错误码说明,比如200是成功,401是未登录,500是服务器错误,每个错误码对应什么场景。
这里给大家一个通用模板,可根据项目调整:
接口名称:[比如:用户注册接口] 接口地址:[测试:http://test.com/api/register;正式:http://prod.com/api/register] 请求方式:[GET/POST/PUT/DELETE] 接口描述:[比如:新用户通过手机号+验证码注册账号]
| 参数名 | 类型 | 是否必填 | 示例值 | 说明 | | ---- | ---- | ---- | ---- | ---- | | phone | string | 是 | 13800138000 | 用户手机号 | | code | string | 是 | 123456 | 短信验证码 | | password | string | 是 | abc123 | 登录密码(需加密) |
| 参数名 | 类型 | 示例值 | 说明 | | ---- | ---- | ---- | ---- | | code | int | 200 | 响应状态码 | | message | string | 注册成功 | 响应信息 | | data | object | {userId:123} | 响应数据体 |
- 200:请求成功 - 400:参数错误(比如手机号格式不对) - 401:未授权(验证码错误) - 500:服务器内部错误
1. Q:接口文档用什么工具写? A:个人项目可以用Markdown,团队项目推荐用Swagger、Postman、YApi,这些工具支持在线预览、自动生成代码,还能实时更新。
2. Q:参数说明要写多细? A:只要是可能影响对接的细节都要写,比如密码是否需要加密、日期格式是“YYYY-MM-DD”还是时间戳、枚举值的可选范围(比如性别参数只能传1/2/3)。
3. Q:接口更新了,文档怎么同步? A:尽量用在线工具维护,更新后自动同步;如果是离线文档,要在开头加版本号,每次更新写清更新内容(比如“2024.5.20:新增age参数”),避免团队拿到旧版本。
写接口文档不是应付任务,而是减少沟通成本的“利器”。抓住规范核心,套对模板,再注意细节,就能写出让团队省心的好文档。