旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API。

一、主要功能

权限管理
YApi 成熟的团队管理扁平化项目权限配置满足各类企业的需求
可视化接口管理
基于 websocket 的多人协作接口编辑功能和类 postman 测试工具，让多人协作成倍提升开发效率
Mock Server
易用的 Mock Server，再也不用担心 mock 数据的生成了
自动化测试
完善的接口自动化测试,保证数据的正确性
数据导入
支持导入 swagger, postman, har 数据格式，方便迁移旧项目
插件机制
强大的插件机制，满足各类业务需求。

二、简介

2.1 首页

登录后进入首页，首页展示了分组与项目。

此时你作为新用户，没有任何分组与项目的权限，因此只能搜索、浏览 “公开项目” 的接口，如果在首页找不到任何项目，请联系管理员将你加入对应项目。

首页头部展示了当前所在的位置、搜索框、新建项目、查看文档和用户信息。
首页左侧展示分组信息，“分组”是“项目”的集合，只有超级管理员可以管理分组。
首页右侧是分组下的项目和成员列表，点击左侧的某个分组，右侧会出现该分组下的项目和成员信息。
点击项目右上角的星星即可关注项目，关注的项目可以在“我的关注”页面查看。

首页

2.2 项目页

点击一个项目，进入项目页，项目页展示了属于该项目的全部接口，并提供项目、接口的全部操作。

此时你作为新用户，只能浏览接口信息，不可以编辑项目或接口，如果需要编辑，请联系管理员将你加入该项目。

项目页左侧的 “接口列表” 展示了该项目下的所有接口，右侧默认显示该项目下所有接口的列表。
点击左侧的某个接口，右侧会出现“预览”、“编辑”和“运行”。
点击左侧的 “测试集合” 使用测试集功能。
点击二级导航的“设置”，项目组长即可编辑项目信息和管理成员列表。
点击二级导航的“动态”，即可查看项目的操作日志。

项目页

2.3 个人中心

鼠标移动到右上角的用户头像或用户名上，即可点击“个人中心”查看个人信息。
在个人信息页面可以查看并修改自己的用户名、密码等信息。

三、创建一个API

新建接口分三步：

获取权限
找到一个项目
新建接口

3.1 获取权限

新用户登录拥有 个人空间 分组下的全部权限，个人空间分组仅自己可见，因此可以在这里任意试用 YApi 的功能。

除此以外没有任何项目或分组的权限，只能浏览已存在分组下面的公开项目。

如果找不到想找的项目，可能是尚未成为项目成员，此时应联系 项目组长 将你加入该项目。

image

想创建分组，请看: 创建分组
想创建项目，请看: 创建项目

想了解更多权限信息，请查看权限列表

3.2 选择项目

如果你已经登录，会在首页右侧看到一些项目 (可以在左侧的分组列表切换分组来查看不同分组下的项目)。
点击一个项目，进入该项目的详情页。

3.3 新建接口

点击左侧接口分组右侧的菜单按钮，选择 添加接口，或者点击接口列表右上角的 添加接口。
选择接口分类，输入接口名称和接口路径，点击 提交。

恭喜你！创建了第一个YApi的接口，你可以看到在左侧看到接口名称，右侧有该接口的信息预览。

四、数据Mock

YApi的 Mock 功能可以根据用户的输入接口信息如协议、URL、接口名、请求头、请求参数、返回数据（返回数据）生成 Mock 接口，这些接口会自动生成模拟数据，创建者可以自由构造需要的数据。

mock地址解析：YApi平台网址 + mock + 您的项目id + 接口实际请求path

假设你 YApi 的部署地址为：http://yapi.xxx.com 然后用这个地址作为示例

mockd 地址： http://yapi.xxx.com/mock/29/api/hackathon/login

注：项目 id 可以在项目设置里查看到

4.1 定义 mock 数据示例

项目 -> 接口编辑 -> 返回数据设置

返回数据设置有两种方式，最新版本默认是基于 json+注释 的方式，另外一种是基于 json-schema 定义数据结构,请根据实际情况灵活选择使用。

4.1.1 方式1. mockjs

image

4.1.1.1 原理

基于 mockjs，跟 Mockjs 区别是 yapi 基于 json + 注释定义 mock 数据，无法使用 mockjs 原有的函数功能。

正则表达式需要基于 rule 书写，示例如下：

{
  "name|regexp": "[a-z0-9_]+?",
  "type|regexp": "json|text|xml"
}

支持替换请求的 query, body 参数

{
  "name": "${query.name}", //请求的url是/path?name=xiaoming, 返回的name字段是xiaoming
  "type": "${body.type}",   //请求的requestBody type=1,返回的type字段是1

}

示例

/**
 * 这是一个接口返回数据示例
 */

{
    "errcode": 0,
    "errmsg": "@word",
    "data": {
        "id": "@id", //@id 随机生成 id
        "name": "@name" //@name 随机生成用户名
    }
}

详细使用文档请查看：Mockjs 官网

4.1.2 方式2. json-schema

image

开启 json-schema 功能后，根据 json-schema 定义的数据结构，生成随机数据。

4.1.2.1 如何生成随机的邮箱或 ip(该方法在v1.3.22之后不再适用)？

点击高级设置，选择 format 选项，比如选择 email 则该字段生成随机邮箱字符串。

4.1.2.2 集成 mockjs

基本书写方式为 mock 的数据占位符@xxx, 具体字段详见Mockjs 官网

image

如果不是以@字符开头的话或者匹配不到Mockjs中的占位符就会直接生成输入的值

4.2 如何使用 Mock

4.2.1 在 js 代码直接请求yapi提供的 mock 地址（不用担心跨域问题）

在代码直接请求 yapi 提供的 mock 地址，以 jQuery 为例：

let prefix = 'http://yapi.xxx.com/mock/2817'
$.post(prefix+'/baseapi/path', {username: 'xxx'}, function(res){
    console.log(res) //返回上图预览部分的数据
})

4.2.2 基于本地服务器反向代理

优点:不用修改项目代码#

4.2. 2.1 基于 nginx 反向代理

location /baseapi
{
proxy_pass   http://yapi.xxx.com/mock/2817/baseapi; #baseapi后面没有"/"
}

4.2. 2.2 基于 Charles 代理

点击 Charles 工具栏下的 tools >> Rewrite Settings 填写如下信息：

image

4.3 mock请求严格模式

版本 v1.3.22 新增 mock 接口请求字段参数验证功能，具体使用方法如下：

打开项目 -> 设置开启 mock 严格模式
针对 query, form 中设置的必须字段会进行必填校验

image
针对 req_body_type 是json schema 格式的数据进行校验

五、自动化测试

传统的接口自动化测试成本高，大量的项目没有使用自动化测试保证接口的质量，仅仅依靠手动测试，是非常不可靠和容易出错的。

YApi 为了解决这个问题，开发了可视化接口自动化测试功能，只需要配置每个接口的入参和对 RESPONSE 断言，即可实现对接口的自动化测试，大大提升了接口测试的效率。

5.1 第一步，测试集合

使用 YApi 自动化测试，第一步需要做得是创建测试集合和导入接口,点击添加集合创建，创建完成后导入接口(同一个接口可以多次导入)。

5.2 第二步，编辑测试用例

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

5.2.1 编辑请求参数

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

5.2.1.1 Mock 参数

Mock 参数每次请求都会生成随机字符串

5.2.1.1.1 变量参数

YApi 提供了强大的变量参数功能，你可以在测试的时候使用前面接口的 参数 或 返回值 作为 后面接口的参数，即使接口之间存在依赖，也可以轻松 一键测试~

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

格式：

$.{key}.{params|body}.{path}

例如：现有两个接口，分别是“导航标题”和“文章列表”

image

文章列表接口需要传参数: 当前标题(id)，而这个 id 需要通过 导航标题 的返回值获取，这时应在 文章列表 的参数输入框中根据前者的 key 找到对应 id。

导航标题 的参数和返回值有如下结构：

参数：

返回值：

则 文章列表 的参数可以如下配置：

其中 .269.params** 即表示 key 值为 269 用例的请求参数，$.269.body 即表示 key 值为 269 用例的返回值。

如果 requestBody 是 json 格式也可以在 json 中写变量参数，如下图：

Tips: 上下拖动测试集合的列表项可以调整测试的顺序。

目前 yapi 中的query，body,header和pathParam的输入参数已经支持点击选择功能。无需自己填写表达式，只需在弹窗中选择需要展示的表达式即可。输入选项包括常量，mock数据，在测试集合中也支持变量选择。具体用法：单击编辑按钮打开表达式生成器，点击需要的数据创建表达式，这里也可以实时查看表达式结果。

Tips: 在测试集合中插入变量参数可以会出现下图的提示信息，这是正常现象。因为该参数只能在各个接口顺序执行的时候才能拉到变量参数中的值

5.2.2 编写断言脚本

编写完请求参数，可通过 js 脚本写断言，实现精准测试，在接口用例页面点击 Test 编辑。

5.3 第三步，运行自动化测试

在测试列表可以看到每个测试用例的 key,还有开始测试、报告等功能

点击开始测试会按照 case 定义的参数从上往下一个一个进行测试，如果顺序有问题，可以拖动调整

测试完成之后，点击报告查看该次请求的结果

5.4 断言脚本公共变量

5.4.1.assert

断言函数，详细 api 可查看 document

5.4.1.1常用 api

assert(value)

判断 value 是否为 truth, 例如 assert(1) 通过， assert(0) 不通过，只要 value 不是 null, 0, false 等值验证通过
assert.equal(actual, expected)

判断 actual 是否等于 expected，例如 assert(1, 1)通过
assert.notEqual(actual, expected)

判断 actual 是否不等于 expected
assert.deepEqual(actual, expected)

假设： actual = {a:1} 是一个对象，即便 expected = {a:1}，如果使用 assert.equal 可能也是不相等的，因为在 js 引用的只是对象的一个指针，需要使用 assert.deepEqual 比较两个对象是否相等
assert.notDeepEaual(actual, expected)

深度比较两个对象是否不相等

5.4.1.2 status

http 状态码

5.4.2.3params

http request params, 合并了 query 和 body

5.4.2.4.body

返回 response body

5.4.2.5.header

返回 response header

5.4.2. 6.records

记录的 http 请求信息，假设需要获取 key 为 555 的接口参数或者响应数据，可通过 records[555].params 或 records[555].body 获取

5.4.2.7.log

log（message）函数,调试时使用，log 信息仅仅在断言失败后打印,失败断言前的信息

log(234)   
assert.equal(status, 400)
log(123)

输出结果： log: 234
AssertionError: 200 == 400

5.2.5 示例


assert.equal(body.errcode, 0)
assert.equal(body.data.group_name, 'testGroup')
assert.equal(status, 200)

5.3 服务端自动化测试

开始测试功能是在浏览器跑自动化测试，他依赖于浏览器的使用环境。服务端自动化测试功能是在YApi服务端跑自动化测试，不需要依赖浏览器环境，只需要访问 YApi 提供的 url 链接就能跑自动化测试，非常的简单易用，而且可以集成到 jenkins。

5.3.1 详细使用方法

点击服务端测试，出现如下弹窗，用户访问该 url 就可以获取当前测试用例的所有测试结果。

5.4 配置通用规则

image

配置通用规则能够使自动化测试，可以基于通用的规则去控制，无需手动一个一个维护case.

YApi

一、主要功能

二、简介

2.1 首页

2.2 项目页

2.3 个人中心

三、创建一个API

3.1 获取权限

3.2 选择项目

3.3 新建接口

四、数据Mock

4.1 定义 mock 数据示例

4.1.1 方式1. mockjs

4.1.1.1 原理

4.1.2 方式2. json-schema

4.1.2.1 如何生成随机的邮箱或 ip(该方法在v1.3.22之后不再适用)？

4.1.2.2 集成 mockjs

4.2 如何使用 Mock

4.2.1 在 js 代码直接请求yapi提供的 mock 地址（不用担心跨域问题）

4.2.2 基于本地服务器反向代理

4.2. 2.1 基于 nginx 反向代理

4.2. 2.2 基于 Charles 代理

4.3 mock请求严格模式

五、自动化测试

5.1 第一步，测试集合

5.2 第二步，编辑测试用例

5.2.1 编辑请求参数

5.2.1.1 Mock 参数

5.2.1.1.1 变量参数

5.2.2 编写断言脚本

5.3 第三步，运行自动化测试

5.4 断言脚本公共变量

5.4.1.assert

5.4.1.1常用 api

5.4.1.2 status

5.4.2.3params

5.4.2.4.body

5.4.2.5.header

5.4.2. 6.records

5.4.2.7.log

5.2.5 示例

5.3 服务端自动化测试

5.3.1 详细使用方法

5.4 配置通用规则

你可能感兴趣的:(YApi)