关于接口文档的建议

请求内容

• 接口名
• 接口描述
• 请求方法
• 请求参数
  1.字段名
  2.是否必填
  3.类型
  4.备注（详细描述当前参数的逻辑、各种情况下对应的错误码。比如：长度限制；若是必填字段，不填写会对应什么错误码，或者不填写忽略当前请求但请求响应是200；若是限制值的字段，如果填写非指定值会怎么样处理以及对应错误码；若是long，如果填写float，是否会向下取整...）

响应内容

• 响应数据格式为json
• 响应结果需统一结构，比如由data、errorCode、msg组成的json内容

响应结果

• 成功的
• 失败的（错误码的说明，此处可和上面的备注内容相关联）

PS

• 主要是入参的不同和响应结果的对应关系尽量详细，以便接口测试能够更顺利进行，减少测试和后端在接口逻辑的沟通上所花的时间。
• data需是对象，其他值则是data的一个属性，比如{data:{name:zhangsan}}，为空时则是{data:{}}
• 请求类型
  GET ：获取数据使用 GET 请求
  POST ：数据操作使用 POST 请求，对安全性有要求的/参数较多不适合用 GET 请求的接口，可以用 POST 请求
• 命名规范
  1.url中统一使用小写字母，url是对大小写敏感的，为了避免歧义，统一使用小写
  2.资源路径使用名词，结尾使用动词（短语）命名，如 /user/get?id=1，user 为资源路径
  3.通用接口名命：获取单个资源用 /get，更新资源用 /update，删除资源用 /delete，增加资源用 /add 或 /save
  4.使用 "-" 分割 url 中的单词，如 /user/get-by-name
  5.接口命名尽量语义化，不要出现易于理解或暴露具体实现方案的命名。如系统中提供两个接口，一个查询 es 提高查询效率，一个查询 mysql 保证实时性，不要命名成 /user/es/get，/user/mysql/get。而是用更加通俗的表述代替，如 /user/

二、示例

• 接口：获取用户信息
• 描述 ：根据用户id获取用户信息
• 请求方式 ：GET
• 路径 ：/user/
• 参数 ：

参数名	是否必传	类型	备注
id	是	number	用户id

• 成功响应示例 ：

 1{
 2  "ok": true,
 3  "code": 200,
 4  "data": {
 5    "username": "哈哈",
 6    "age": 20,
 7    "email": "24*******@qq.com"
 8  },
 9  "msg": null
10}

• 失败响应示例 ：

1{
2  "ok": false,
3  "code": 1000001,
4  "data": null,
5  "msg": "用户不存在"
6}

---

下面是为什么写这个文档的原因（吐槽给老大，老大就叫我写文档，然后给后端讨论，所以说吐槽需谨慎）

背景

一个基础模块需要做接口测试，因为各种原因（时间急+后端懒），接口文档不完善，但抱着互相理解的精神，硬着头皮先上了。期间遇到异常情况会怎么样处理等逻辑问题，就和后端进行沟通（很影响效率）
并且后来因为各种情况，导致架构设计都改变（设计阶段，发现问题并修改），原因如下，但不仅限于：路径的不规范、请求方法的不规范、开始用于加快查询的二进制数字段不能用（因为所使用的插件不能根据二进制分表）、字段的类型不符合场景（一个字段的类型改成了对象，该字段用来存储的是key-value结构的数据，可以用于搜索和统计）、逻辑的改变等。。。
所以就导致接口测试要不断修改和回归，因为时间原因（主要重复工作觉得烦），然后打算写脚本来跑（脚本优点：封装起来修改很快；灵活，想要什么就自己写）
但是因为文档很不规范，连参数错误对应的响应数据都没，所以导致判断条件也写的很粗暴，影响测试质量（很多错误是直接500，有些字段不符合规则直接略过不执行但是却还响应200，很不规范）
其实各种不规范也是可以理解，因为这个项目组组成不久，时间又急，这种详细设计文档，大佬没时间来写，负责的后端人员就随性发挥了。