接口文档

引言

本文献给那些处于流程较为粗糙公司的同行们。

在我们日常工作与项目中,文档是一件非常重要的事情,个人认为,优先程序甚至高于代码;

作为技术人员,通过文档,可以了解到项目的背景、需求、目标、具体细节点详情,在极端情况下甚至能够重新开发一套相同功能的服务;

与之对应,若仅有代码,对于个人经验而言,通常需要一段时间脱产进行业务逻辑梳理与代码熟悉,费时费心。
在代码质量较差的情况下,难免会有删库跑路的冲动。

笔者在上一份工作离职交接时,由于文档写的比较完善,交接的同事甚至还称赞不已。与子与人,大家应该都具有这样的技能,造福自己,造福整个行业。

以下为笔者整理的一个接口文档示例,使用markdown模式编写,更符合行业趋势。

接口名称

接口说明,具体功能、使用限制等

请求地址

/api/demo

  • dev: ip/domain:port
  • uat: ip/domain:port
  • test: ip/domain:port
  • pro: ip/domain:port

请求方式

POST/GET

请求头

1
2
3
4
Content-Type: application/json
token: xx
x-forward-ip: xx
...

请求参数

1
2
3
4
5
{
"id": 1, // 数据id
"key": "xx", // 搜索词
"pageNum": "当前页数"
}

返回结果

正常
1
2
3
4
5
6
7
8
9
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"name": "xx",
"create_time": "2021-01-10 10:10:10"
}
}
异常
1
2
3
4
5
{
"code": !0,
"message": "success",
"data": null
}
异常说明
code remark
1 业务异常,详情见message字段
999 用户未登录
-1 系统异常,请稍后重试
-2 接口限流,请稍后重试
-3 没有权限