请求内容
- 接口名
- 接口描述
- 请求方法
- 请求参数
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，很不规范）
其实各种不规范也是可以理解，因为这个项目组组成不久，时间又急，这种详细设计文档，大佬没时间来写，负责的后端人员就随性发挥了。
网友评论