web - 后端接口编写规范示例（API）

前言

当后端完成一个 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（简易示例）

写在后面

目前市面上有很多网站提供 团队文档协作 服务，可以使用它们解决方案，团队可以在线撰写文档，可被团队所有人可见。大大减少沟通成本，这里不列出了，避免广告嫌疑。