前言
当后端完成一个 API
接口时,通常需要 与前端人员沟通接口的细节,这时候,一个文档就能节省很多效率,大大减少沟通成本,如何撰写一份规范文档呢?
功能描述
用最简洁清晰的语言,让不懂后端的前端一看就懂。
主要说明该方法实现什么功能(很重要),涉及术语需要标注。
URL地址
例如:/admin/user/
请求方式
调用该接口前端需要使用什么方式来请求(GET / POST / PUT / DELETE …)
请求参数
此块最好使用表格来描述。
调用该接口时,前端需要传递哪些参数值,主要有以下几个方面:
- 【字段】:对应的字段名称,如
userName
/pwd
。 - 【说明】:对于该字段的说明,如
用户名
/密码
。 - 【类型】:对于该字段类型,如
Array
/Object
。 - 【是否必填】:
Y/N
/True/False
- 【备注】:对于该接口有什么备注。
返回结果
请求该接口方法预期返回什么样的结果。
请求示例
对该方法做一个请求示例,来进一步减少前端思考成本。
wx.request({
url: 'test.php', //接口地址
data: {
x: '',
y: ''
},
header: {
'content-type': 'application/json' // 默认值
},
success (res) {
console.log(res.data)
}
})
返回示例
对该方法做一个返回示例,来进一步减少前端思考成本。
{
code:100,
message: '请求示例',
data: {
..
}
}
状态码说明
后端 自定义状态码 必须要写此状态码说明。
扫描二维码关注公众号,回复: 11559522 查看本文章
对返回的状态码说明,如返回 400
代表错误,200
代表正常。
到这里就结束了,当然要遵守公司需求以及公司制定的规范。
DEMO(简易示例)
写在后面
目前市面上有很多网站提供 团队文档协作 服务,可以使用它们解决方案,团队可以在线撰写文档,可被团队所有人可见。大大减少沟通成本,这里不列出了,避免广告嫌疑。