1. 简介

1.1 什么是Yapi

Yapi是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API，Yapi还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

特性：

  • 基于 Json5 和 Mockjs 定义接口返回数据的结构和文档，效率提升多倍。
  • 扁平化权限设计，即保证了大型企业级项目的管理，又保证了易用性。
  • 类似 postman 的接口调试。
  • 自动化测试, 支持对 Response 断言。
  • MockServer 除支持普通的随机 mock 外，还增加了 Mock 期望功能，根据设置的请求过滤规则，返回期望数据。
  • 支持 postman, har, swagger 数据导入。
  • 免费开源，内网部署，信息再也不怕泄露了。

    1.2 服务器部署Yapi

    1、下载并启动 MongoDB ```shell sudo mkdir -p /home/yapi/data/db

docker run —name mongo-yapi \ -v /home/yapi/data/db:/data/db \ -p 27017:27017 \ -d mongo:4.4.3

  1. 2、下载yapi镜像
  2. ```shell
  3. # 下载失败
  4. docker pull yapi:1.8.5
  6. #别人制作的1.8.5版本
  7. docker pull registry.cn-zhangjiakou.aliyuncs.com/barcke-util/yapi

3、在宿主机上自定义yapi配置文件 /home/yapi/config/config.json，内容为：

这里邮箱端口换成 25 不可用。

sudo mkdir -p /home/yapi/config

sudo sh -c 'cat > /home/yapi/config/config.json <<EOF
{
  "port": "4000",
  "adminAccount": "admin@admin.com",
  "timeout": 120000,
  "db": {
    "servername": "mongo-yapi",
    "DATABASE": "yapi",
    "port": 27017
  },
  "mail": {
    "enable": true,
    "host": "smtp.qq.com",
    "port": 465,
    "from": "2711845964@qq.com",
    "auth": {
      "user": "2711845964@qq.com",
      "pass": "umnnlyikqlfjdegi"
    }
  }
}
EOF'

4、初始化 MongoDB 数据库索引及创建管理员账号。账号：admin@admin.com，密码：ymfe.org 

docker run -it --rm \
-v /home/yapi/config/config.json:/api/config.json \
--link mongo-yapi:mongo \
--entrypoint npm \
--workdir /api/vendors \
yapi:1.8.5 \
run install-server

5、启动yapi服务

docker run --name yapi --restart=always \
-v /home/yapi/config/config.json:/api/config.json \
--link mongo-yapi:mongo \
--workdir /api/vendors \
-p 4000:4000 \
-d yapi:1.8.5 \
server/app.js

6、查看容器运行状态：docker ps。
7、访问应用 http://192.168.58.12:4000/login，输入之前的默认账号：admin@admin.com，密码：ymfe.org。
image.png

1.3 安装Chrome插件cross-request

发送请求需要添加 Chrome 插件 crossRequest，在开发工具中启动开发者模式手动添加 crossRequest.zip 解压目录。crossRequest.zip
Yapi使用指南 - 图2

2. 基本配置

2.1 登录与注册

访问 http://hostip:3000/login 页面，进入到 Yapi 登录与注册页面，输入用户名、邮箱、密码。我这里注册了 dev1、dev2、pm 3 个用户。
image.png

2.2 首页

登录后会进入首页，首页重点有两大块内容，左侧分组，右侧项目。
image.png
为了方便说明，我这里新建一个分组若依开发平台，在右侧成员列表中添加成员 dev1、dev2，并添加项目 RuoYi-Vue。
image.png
image.png

2.3 用户权限

项目中的用户有三种：组长、开发者、访客。
组长分为 分组组长 与 项目组长，创建分组时指定的组长就是分组组长，创建项目指定的组长就是项目组长，分组组长权限大于项目组长。

  • 分组创建好之后普通成员（包括分组组长）只能修改，不能删除，如有需要，联系管理员。分组组长允许删除其下所有的项目。
  • 项目组长允许对其所在的项目进行删改，对其他项目不允许。

开发者是不允许删除任何项目的，一般就是定义接口进行测试。
访客只允许访问当前分组下所有公有项目。
项目权限

操作 游客 项目开发者 项目组长 超级管理员
浏览公开项目与接口 ✓ ✓ ✓ ✓
浏览私有项目与接口 ✓ ✓ ✓
编辑项目信息 ✓ ✓ ✓
新建接口 ✓ ✓ ✓
编辑接口 ✓ ✓ ✓
编辑项目头像 ✓ ✓
删除项目 ✓ ✓

分组权限

操作 游客 分组开发者 分组组长 超级管理员
浏览分组 ✓ ✓ ✓ ✓
在分组中新建项目 ✓ ✓ ✓
编辑分组信息 ✓ ✓
管理分组成员 ✓ ✓
删除分组
✓

2.4 项目配置

2.4.1 项目成员管理

进入 RuoYi-Vue 项目之后，点击“成员管理”，添加项目成员，指定组长。
image.png

2.4.2 定义接口路径和Tag

点击“设置”》“项目配置”，定义接口路径、tag 信息等等。

这里普通项目成员是没有权限的，只有组长才能进行设置。

image.png

2.4.3 配置环境

根据实际情况建立 dev、test 等环境，指明域名、Header、Cookie、global 等参数信息。
image.png

2.4.4 请求配置

请求配置包括请求参数处理脚本和响应数据处理脚本两部分。通过自定义 javascript 脚本方式改变请求的参数和返回的 response 数据。他的使用场景如下：

  • 接口请求参数需要加密及返回 response 解密。
  • 接口请求参数需要添加计算 token。

    我这里进行判断：将响应结果中的 token 保存到变量中，请求时读取变量中的值设置 token。

image.png

2.4.5 添加分类及接口

在 RuoYi-Vue 界面上添加分类“登录验证”。
image.png
在对应的分类下添加接口，指明接口路径、请求方法、请求参数等。
image.png
为了方便测试，这里多创建几个分类及接口。

3. 接口测试

这里以“岗位管理”增删查改为例

3.1 获取所有列表

很简单的一个 get 请求，定义好接口的 url 路径，发送即可查看结果。
image.png

3.2 根据岗位编号获取详细信息

get 请求携带路径参数，可以直接指定 postId 为某一个固定值，也可以使用 mock 语法自定义范围，取一个随机值。

@integer(1,4)：随机从 1-4 里获取一个整数作为当前参数值。

image.png

3.3 新增岗位

post 请求，需要设置请求参数，使用 mock 语法定义参数的取值范围。
image.png
测试结果如下：
image.png

3.4 修改岗位

和增加功能类似，请求参数多了一个 postId。

@Integer(5,100)：表示从 5-100 随机选取一个值。

image.png
测试结果如下：
image.png

3.5 删除岗位

请求携带路径变量 postIds，为一个数组类型，参数中可以设置 1 个或者多个。
image.png

4. Mock

4.1 什么是Mock

mock 就是在测试过程中，对于某些不容易构造或者不容易获取的对象，用一个虚拟的对象来创建以便测试的测试方法。官方文档：http://mockjs.com/examples.html。
Yapi 中有四种定义 mock 的方式，其优先级：Mock 期望 > 自定义 Mock 脚本 > 项目全局 mock 脚本 > 普通 Mock。如果前面匹配到 Mock 数据，后面 Mock 则不返回。

使用场景：

  1. 你测试的 A 接口依赖 B 接口，但是开发还没有开发完成 B 接口，这时候你就可以 mockB 接口模拟 B 返回的值，然后去测 A 接口。
  2. 你所依赖的外部接口没有开放，比如测支付这一块，支付宝或者微信的支付接口还没有开放，那这时候也可以用 mock 来解决。

    4.2 Mock自定义脚本

    在前端开发阶段，对于某些接口，业务相对复杂，而 UI 端也需要根据接口返回的不同内容去做相应的处理，而自定义脚本可以根据用户请求的参数修改返回内容。
    image.png

    4.3 Mock期望

    期望是根据设置的请求参数及过滤规则，返回期望数据，这个数据是确定的而不是随机的数据。这个期望的数据来源主要是写完脚本后，通过 postman 或者浏览器直接访问获得数据结构，再修改获得的。
    image.png

    4.4 项目全局Mock脚本

    全局脚本是在项目层面上全局设置公共的mock数据，需要项目组长才有权限编辑，主要用来输出一些通用的数据，比如返回空数据等等。
    image.png

    4.5 普通Mock

    普通 Mock 数据在接口编辑时处理，数据来源是写完脚本后，通过 postman 或者浏览器直接访问获得数据结构，导入json，然后再把脚本定义的 mock 稍微转化而来。
    image.png

    4.6 测试Mock

    点击 mock 地址就可以查看结果。
    image.png
    image.png

    4.7 常用mock表达式

    @boolean
@interger(min?,max?)   //生成min-max的整数
@float(min?,max?,dmin?,dmax?)  // 生成min-max,小数点位数为dmin-dmax的浮点数
@string(min?,max?)或@string(length)   // 生成字符串长度范围或者定长字符串
@date(format?)  // 生成日期   @date('yyyy-MM-dd')
@time(fotmat?)   //生成时间  @time('HH:mm:ss')
@datetime(format?)   //生成日期和时间 @datetime('yyyy-MM-dd HH:mm:ss') 
@now()  //现在的时间和日期   "2019-06-26 08:49:00"
@image(size?,background?,foreground?,format?,text?)  //生成图片  @image('200*100','gray','#fff','hello')
@color()    //随机生成16进制颜色
@paragraph(min?,max?) 或@paragraph(len)    //生成英文段落
@cparagraph(min?,max?)或@cparagraph(len)    //生成中文段落
@title(min?,max?)或@title(len)    //生成英文标题
@ctitle(min?,max?)或@ctitle(len)      //生成中文标题
@name()   //英文姓名
@cname()    //中文姓名
@url(protocol?)    //生成url   @url('https')
@domain(main?)     //生成域名  @url('baidu.com')    "dvtjmt.baidu.com"
@email(main?)     //生成邮箱  @email('gmail.com')
@ip    //生成IP地址
@province     //生成省份
@city     //生成城市
@county(true)    //生成详细地址
@guid()    //生成设备ID
@increment(step?)    //生成递增ID

    5. 自动化测试

    5.1 准备测试集合

    1、在“测试集合”中点击“添加集合”。
    image.png

2、点击左侧的集合分类，导入对应的接口中到集合。
image.png
3、对需要设置路径参数和请求的参数进行设置并更新，确保每个请求数据都完整。
image.png

5.2 编辑测试用例

编辑测试用例主要涉及两个方面，一个是请求参数，另外一个是断言脚本。

5.2.1 编辑请求参数

请求参数可以填写期望的字符串，YApi 还提供了 Mock 参数和 变量参数。Mock 参数用来生成随机字符串，变量参数是为了解决请求参数依赖其他接口的返回数据或参数。
image.png

5.2.2 编辑变量参数

YApi 提供了强大的变量参数功能，你可以在自动化测试的时候使用前面接口的参数或返回值作为后面接口的参数，即使接口之间存在依赖，也可以轻松一键测试。
格式：$.{key}.{params|body}.{path}

参数只能是测试过程中排在前面的接口中的变量参数。

例如：“根据岗位编号获取岗位信息”这个接口要用到“获取岗位列表”接口中的返回值。

1、查看“获取岗位列表”接口的 key 值，以及结果返回值。
image.png
image.png

2、根据变量参数获取前面接口结果的返回值。
image.png
3、查看执行结果。
image.png

5.2.3 编写断言脚本

编写完请求参数，可通过 js 脚本写断言，实现精准测试，在接口用例页面点击 Test 编辑。
image.png
或者可以在测试集合界面，进行通用规则配置，定义全局测试脚本。
image.png

5.3 运行自动化测试

点击某一个测试集合，选择“测试用例环境”，点击“开始测试”，即可生成测试报告。
image.png

5.4 服务端测试

1、点击“服务端测试”》“选择测试用例环境” 》“开启消息通知及下载数据”，复制生成的 url。
image.png
2、将复制的 url 直接放到浏览器运行就可以查看结果。
image.png
3、将刚才复制的 url 放到项目根目录下的 .gitlab-ci.yaml 文件中，这样当用户提交代码的时候会自动去进行 api 测试。

api-test-job:
  stage: api-test
  image: $DOCKER_REGISTRY/library/curl-alpine:latest
   script:
    - echo "API测试-----使用yapi"
    - curl "http://192.168.58.12:4000/api/open/run_auto_test?id=184&token=10fb7893bd2e11c1144e841cabe41cee20f52cae4a64c37cce1cf92cf1b90492&env_41=test&mode=html&email=true&download=false"
    - curl "http://192.168.58.12:4000/api/open/run_auto_test?id=187&token=10fb7893bd2e11c1144e841cabe41cee20f52cae4a64c37cce1cf92cf1b90492&env_41=test&mode=html&email=true&download=false"
    - curl "http://192.168.58.12:4000/api/open/run_auto_test?id=190&token=10fb7893bd2e11c1144e841cabe41cee20f52cae4a64c37cce1cf92cf1b90492&env_41=test&mode=html&email=true&download=false"
    - curl "http://192.168.58.12:4000/api/open/run_auto_test?id=193&token=10fb7893bd2e11c1144e841cabe41cee20f52cae4a64c37cce1cf92cf1b90492&env_41=test&mode=html&email=true&download=false"
    - curl "http://192.168.58.12:4000/api/open/run_auto_test?id=196&token=10fb7893bd2e11c1144e841cabe41cee20f52cae4a64c37cce1cf92cf1b90492&env_41=test&mode=html&email=true&download=false"
    - curl "http://192.168.58.12:4000/api/open/run_auto_test?id=199&token=10fb7893bd2e11c1144e841cabe41cee20f52cae4a64c37cce1cf92cf1b90492&env_41=test&mode=html&email=true&download=false"
  tags:
    - docker
  only:
    - master

image.png
4、用户提交代码，查看 api-test 结果。
image.png