fork from bc4552c5a8

docs/documents/CHANGELOG.md

@@ -0,0 +1 @@
+!!!include(CHANGELOG.md)!!!

docs/documents/SUMMARY.md

@@ -0,0 +1,57 @@
+# YApi
+
+### 快速上手
+
+* [认识YApi](index.md)
+* [创建第一个API](quickstart.md)
+
+### 进阶篇
+* [权限](manage.md)
+* [项目操作](project.md)
+  * [基本设置](project.md#基本设置)
+  * [新建项目](project.md#新建项目)
+  * [修改项目](project.md#修改项目)
+  * [项目迁移](project.md#项目迁移)
+  * [项目拷贝](project.md#项目拷贝)
+  * [配置环境](project.md#配置环境)
+  * [请求配置](project.md#请求配置)
+  * [token配置](project.md#token)
+  * [全局mock](project.md#全局mock)
+* [接口操作](api.md)
+  * [接口设置](api.md#接口配置)
+  * [接口运行](api.md#接口运行)
+* [数据Mock](mock.md)
+  * [方式1. mockjs](mock.md#方式1. mockjs)
+  * [方式2. json-schema](mock.md#方式2. json-schema)
+  * [如何使用](mock.md#如何使用 Mock)
+  * [严格模式](mock.md#mock请求严格模式)
+* [高级Mock](adv_mock.md)
+  * [Mock 期望](adv_mock.md#Mock 期望)
+  * [自定义脚本](adv_mock.md#自定义 Mock 脚本)
+* [自动化测试](case.md)
+  * [第一步，测试集合](case.md#第一步，测试集合)
+  * [第二步，编辑测试用例](case.md#第二步，编辑测试用例)
+  * [第三步，运行自动化测试](case.md#第三步，运行自动化测试)
+  * [断言脚本公共变量](case.md#断言脚本公共变量)
+  * [服务端自动化测试](case.md#服务端自动化测试)
+* [数据导入](data.md)
+  * [Postman 数据导入](data.md#Postman 数据导入)
+  * [HAR 数据导入](data.md#HAR 数据导入)
+  * [Swagger 数据导入](data.md#Swagger 数据导入)
+  * [JSON 数据导入](data.md#YApi接口JSON数据导入)
+  * [通过命令行导入接口数据](data.md#通过命令行导入接口数据)
+* [数据导出](export-data.md)
+
+
+### 自定义
+* [插件](plugin-index.md)
+  * [插件开发](plugin-dev.md)
+  * [插件列表](plugin-list.md)
+  * [钩子](plugin-hooks.md)
+* [二次开发](redev.md)
+
+---
+* [常见问题解答](qa.md)
+* [版本记录](CHANGELOG.md)
+
+

docs/documents/adv_mock.md

@@ -0,0 +1,105 @@
+# 高级Mock
+高级 Mock 分为`Mock 期望`和`自定义 Mock 脚本`两种方式。
+
+## Mock 期望
+在测试时，很多时候需要根据不同的请求参数、IP 返回不同的 HTTP Code、HTTP 头和 JSON 数据。
+
+Mock 期望就是根据设置的请求过滤规则，返回期望数据。
+
+### 使用方法
+1. 进入接口详情页，点击『高级 Mock』选项。
+<div class="doc-img-wrapper"><img class="doc-img-r" src="./images/usage/adv-mock-case1.png"/></div>
+2. 点击『添加期望』，填写过滤规则以及期望返回数据，点击『确定』保存。
+<div class="doc-img-wrapper"><img class="doc-img-r" src="./images/usage/adv-mock-case3.png"/></div>
+<div class="doc-img-wrapper"><img class="doc-img-r" src="./images/usage/adv-mock-case4-new.png"/></div>
+3. 然后尝试在浏览器里发送符合规则的请求，查看返回的数据是否符合期望。
+<div class="doc-img-wrapper"><img class="doc-img-r" src="./images/usage/adv-mock-case5-new.png"/></div>
+
+### 期望填写
+
+基本信息
+
+* 期望名称：给此条期望命名
+* IP 过滤：请求的 IP 是设置的地址才可能返回期望。默认 IP 过滤关闭，任何 IP 地址都可能返回期望。
+* 参数过滤：请求必须包含设置的参数，并且值相等才可能返回期望。参数可以在 Body 或 Query 中。
+
+响应
+
+* HTTP Code：期望响应的 HTTP 状态码
+* 延时：期望响应的延迟时间
+* HTTP 头：期望响应带有的 HTTP 头
+* 返回 JSON：期望返回的 JSON 数据
+
+
+## 自定义 Mock 脚本
+在前端开发阶段，对于某些接口，业务相对复杂，而 UI 端也需要根据接口返回的不同内容去做相应的处理。
+
+YApi 提供了写 JS 脚本方式处理这一问题，可以根据用户请求的参数修改返回内容。
+
+### 全局变量
+请求
+
+- `header` 请求的 HTTP 头
+- `params` 请求参数，包括 Body、Query 中所有参数
+- `cookie` 请求带的 Cookies
+
+响应
+
+- `mockJson` 
+  接口定义的响应数据 Mock 模板
+
+- `resHeader` 
+响应的 HTTP 头
+
+- `httpCode` 
+响应的 HTTP 状态码
+
+- `delay` 
+Mock 响应延时，单位为 ms
+
+- `Random` 
+Mock.Random 方法，可以添加自定义占位符,详细使用方法请查看 <a href="https://github.com/nuysoft/Mock/wiki/Mock.Random">Wiki</a>
+
+### 使用方法
+1. 首先开启此功能
+2. Mock 脚本就是用 JavaScript 对 `mockJson` 变量修改,请避免被全局变量(httpCode, resHeader, delay)的修改
+
+
+### 示例1, 根据请求参数重写 mockJson
+```
+if(params.type == 1){
+  mockJson.errcode = 400;
+  mockJson.errmsg = 'error';
+}
+
+if(header.token == 't'){
+  mockJson.errcode = 300;
+  mockJson.errmsg = 'error';
+}
+
+if(cookie.type == 'a'){
+  mockJson.errcode = 500;
+  mockJson.errmsg = 'error';
+}
+
+```
+
+### 示例2, 生成高度自定义数据内容
+```
+var a = [1,1,1,1,1,1,1,1,1,1]
+
+mockJson = {
+    errcode: 0,
+    email: Random.email('qq.com'),
+    data: a.map(function(item){
+        return Random.city() + '银行'
+    })
+}
+
+```
+
+
+## Mock 优先级说明
+请求 Mock 数据时，规则匹配优先级：Mock 期望 > 自定义 Mock 脚本 > 项目全局 mock 脚本 > 普通 Mock。
+
+如果前面匹配到 Mock 数据，后面 Mock 则不返回。

docs/documents/api.md

@@ -0,0 +1,64 @@
+# 接口设置
+进入项目页，可以看到项目下的所有接口，需要注意的是，YApi有 `接口集合` 和 `测试集合` 两个概念。
+
+- `接口集合` 将接口进行分类，使接口结构更清晰，一个接口只能属于一个集合，且不允许与其他接口重名。
+- `测试集合` 为了方便我们测试接口，`测试集合` 将若干接口组合在一起，在这里一个接口可以属于不同集合。
+
+## 接口配置
+
+[新建接口](./quickstart.md#新建接口) 后，点击新添加的接口，右侧可以看到接口的预览信息，点击右侧的 `编辑` Tab项进入编辑面板。
+
+在该面板中你可以看到接口的基本信息(接口名称、分类、路径)，除此以外，你还可以完善以下接口信息：
+
+### 基本设置
+
+- 接口路径：可以更改 HTTP 请求方式，并且支持 restful 动态路由，例如 /api/{id}/{name}, id和name是动态参数
+- 选择分类：可以更改接口所在分类
+- 状态：用于标识接口是否开发完成。
+- Tag：用于标识接口tag信息（v1.3.23+）,在接口list页可以根据tag过滤接口
+
+<img src="./images/baseSet.png" />
+
+### 请求参数设置
+
+- Query参数： 接口 url 的查询字符串，点击『添加Query参数』按钮来添加参数，可以通过拖动来交换参数位置
+- 请求Body：http 请求 body 部分，如果http请求方式是 post, put 等请求方式时会有 req_body 部分。req_body_type 形式有4种，分别是 form, json, file 和 raw 。
+- Headers:  http 请求头字段，在 req_body 形式是 form 格式下会在 header 中自动生成 'Content-Type	application/x-www-form-urlencoded'，其他3种格式也会自动生成不同 header
+
+<img src="./images/requestSet.png" />
+
+### 返回数据设置
+
+- 返回数据分为 `json` & `raw` 两种形式。基于 mockjs （具体使用方法详见[Mock 介绍](./mock.md)）和 json5，使用注释方式写参数说明。 为了方便数据编写可以按F9来使用全局编辑
+- 选择json-schema 则进入了 json 结构可视化编辑器形式, 数据以 json schema 格式解析 <a  target="_blank" href="https://www.jianshu.com/p/8278eb2458c4?winzoom=1">快速入门 Json Schema </a>。
+
+<img src="./images/jsonSchema.png" />
+
+
+
+### 备注 & 其他
+- 接口描述: 用简短的文字描述接口的作用。
+- 邮件通知：开启后将此次接口的改动以邮件的形式发送至项目组所有成员和关注该项目的成员（邮件默认情况下自动开启）
+- 开放接口：默认为关闭状态，用户可以在 数据导出 时选择只导出公开接口
+
+
+## 接口运行
+接口运行功能，是用来测试真实接口的，类似『Postman』的功能。
+
+点击运行 tab ,可进入到接口测试页面，首先安装『chrome crossRequest』扩展，才可正常使用此功能。
+
+点击保存按钮可把当前接口保存到测试集，方便下次调试。
+
+> 安装完插件记得刷新页面
+
+<img src="./images/interface_run.png" height="50%"/>
+
+### 接口返回数据验证
+
+版本 v1.3.22 新增返回数据验证功能， 如果接口的返回数据格式为json schema 在接口运行时会对接口返回数据和定义数据格式进行校验
+
+<img src="./images/interface_run_valid.png"/>
+
+
+
+

docs/documents/case.md

@@ -0,0 +1,176 @@
+# 自动化测试
+
+传统的接口自动化测试成本高，大量的项目没有使用自动化测试保证接口的质量，仅仅依靠手动测试，是非常不可靠和容易出错的。
+
+YApi 为了解决这个问题，开发了可视化接口自动化测试功能，只需要配置每个接口的入参和对 RESPONSE 断言，即可实现对接口的自动化测试，大大提升了接口测试的效率。
+
+## 第一步，测试集合
+使用 YApi 自动化测试，第一步需要做得是创建测试集合和导入接口,点击添加集合创建，创建完成后导入接口(同一个接口可以多次导入)。
+
+![](case-col.png)
+
+![](import-case.png)
+
+
+## 第二步，编辑测试用例
+编写测试用例主要涉及两个方面，一个是请求参数，另外一个是断言脚本。
+
+### 编辑请求参数
+
+请求参数可以填写期望的字符串，YApi 还提供了 Mock 参数和 变量参数。Mock参数用来生成随机字符串，变量参数是为了解决请求参数依赖其他接口的返回数据或参数。
+
+#### Mock 参数
+
+Mock 参数每次请求都会生成随机字符串
+
+<img  class="doc-img" style="width:100%" src="./images/usage/case-edit.jpg"  />
+
+##### 变量参数
+
+YApi 提供了强大的变量参数功能，你可以在测试的时候使用前面接口的 `参数` 或 `返回值` 作为 `后面接口的参数`，即使接口之间存在依赖，也可以轻松 **一键测试~**
+
+> Tips: 参数只能是测试过程中排在前面的接口中的变量参数
+
+格式：
+
+```
+$.{key}.{params|body}.{path}
+```
+
+例如：现有两个接口，分别是“导航标题”和“文章列表”
+<img class="doc-img" style="width: 678px;" src="./images/usage/case_key_list.png" />
+
+文章列表接口需要传参数: `当前标题(id)`，而这个 id 需要通过 `导航标题` 的返回值获取，这时应在 `文章列表` 的参数输入框中根据前者的 key 找到对应 id。
+
+`导航标题` 的参数和返回值有如下结构：
+
+<div style="margin: 16px 0;">
+  <span style="display: inline-block; width: 60px;vertical-align: top;">参数：</span>
+  <img style="width: 165px;" src="./images/usage/case_key_res_query.png" />
+</div>
+<div style="margin: 16px 0;">
+  <span style="display: inline-block; width: 60px;vertical-align: top;">返回值：</span>
+  <img style="width: 122px;" src="./images/usage/case_key_res.png" />
+</div>
+
+则 `文章列表` 的参数可以如下配置：
+<img  class="doc-img" style="width: 624px;" src="./images/usage/case_key_query.png" />
+
+其中 **$.** 是使用 **动态变量** 的标志，$.269.**params** 即表示 key 值为 269 用例的请求参数，$.269.**body** 即表示 key 值为 269 用例的返回值。
+
+如果 requestBody 是 json 格式也可以在 json 中写变量参数，如下图：
+<img  class="doc-img" style="width: 624px;" src="./images/usage/case_key_body_json.png" />
+
+> Tips: 上下拖动测试集合的列表项可以调整测试的顺序。
+
+目前 yapi 中的`query`，`body`,`header`和`pathParam`的输入参数已经支持点击选择功能。无需自己填写表达式，只需在弹窗中选择需要展示的表达式即可。 输入选项包括`常量`，`mock数据`，在测试集合中也支持`变量`选择。具体用法：单击编辑按钮打开表达式生成器，点击需要的数据创建表达式，这里也可以实时查看表达式结果。
+
+<img class="doc-img" style="width: 800px;" src="./images/usage/modal-postman.gif"  />
+
+> Tips: 在测试集合中插入变量参数可以会出现下图的提示信息，这是正常现象。因为该参数只能在各个接口顺序执行的时候才能拉到变量参数中的值
+
+<img class="doc-img" style="width: 800px;" src="./images/usage/modal-postman-tips.png"  />
+
+### 编写断言脚本
+
+编写完请求参数，可通过 js 脚本写断言，实现精准测试，在接口用例页面点击 Test 编辑。
+
+![](test-case.png)
+
+## 第三步，运行自动化测试
+
+<img class="doc-img" style="width: 618px;" src="./images/usage/case-list.gif"  />
+
+在测试列表可以看到每个测试用例的 key,还有 开始测试、报告等功能
+
+点击开始测试会按照 case 定义的参数从上往下一个一个进行测试，如果顺序有问题，可以拖动调整
+
+测试完成之后，点击报告查看该次请求的结果
+
+## 断言脚本公共变量
+
+### 1.assert
+
+断言函数，详细 api 可查看 <a target="_blank" href="https://nodejs.org/dist/latest-v8.x/docs/api/assert.html">document</a>
+
+#### 常用 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)
+
+  深度比较两个对象是否不相等
+
+#### 2.status
+
+http 状态码
+
+#### 3.params
+
+http request params, 合并了 query 和 body
+
+#### 4.body
+
+返回 response body
+
+#### 5.header
+
+返回 response header
+
+#### 6.records
+
+记录的 http 请求信息，假设需要获取 key 为 555 的接口参数或者响应数据，可通过 records[555].params 或 records[555].body 获取
+
+#### 7.log
+
+log（message） 函数,调试时使用，log 信息仅仅在断言失败后打印,失败断言前的信息
+
+```
+log(234)   
+assert.equal(status, 400)
+log(123)
+```
+输出结果：
+log: 234  
+AssertionError: 200 == 400
+
+
+### 示例
+
+```
+
+assert.equal(body.errcode, 0)
+assert.equal(body.data.group_name, 'testGroup')
+assert.equal(status, 200)
+```
+
+## 服务端自动化测试
+
+
+开始测试功能是在浏览器跑自动化测试，他依赖于浏览器的使用环境。服务端自动化测试功能是在YApi服务端跑自动化测试，不需要依赖浏览器环境，只需要访问 YApi 提供的 url 链接就能跑自动化测试，非常的简单易用，而且可以集成到 jenkins。
+
+### 详细使用方法
+
+点击服务端测试，出现如下弹窗，用户访问该 url 就可以获取当前测试用例的所有测试结果。
+
+<img src="./images/autoTest.png" />
+<img src="./images/autoTestResult.png" />
+
+## 配置通用规则
+![](2019-01-15-14-05-46.png)
+
+配置通用规则能够使自动化测试，可以基于通用的规则去控制，无需手动一个一个维护case.

docs/documents/data.md

@@ -0,0 +1,109 @@
+# 数据导入
+
+在数据管理可快速导入其他格式的接口数据，方便快速添加接口。YApi 目前支持 postman, swagger, har 数据导入。
+
+v1.3.23+ 增加数据导入的3种同步方式  normal, good, mergin
+
+1. 普通模式(normal)：不导入已存在的接口；   
+2. 智能合并(good)：已存在的接口，将合并返回数据的 response，适用于导入了 swagger 数据，保留对数据结构的改动；例如，用户对字段code 添加了mock信息, 当再次数据导入的时候 mock 字段将不会被覆盖
+3. 完全覆盖(mergin)：不保留旧数据，完全使用新数据，适用于接口定义完全交给后端定义， 默认为 normal
+
+## Postman 数据导入
+
+1.首先在 postman 导出接口
+
+<div><img class="doc-img" style="width:50%"  src="./images/usage/postman-1.jpg" /></div>
+
+2.选择 collection_v1,点击 export 导出接口到文件 xxx
+
+<div><img  class="doc-img"  style="width:70%"  src="./images/usage/postman-2.jpg" /></div>
+
+3.打开 yapi 平台，进入到项目页面，点击数据管理，选择相应的分组和 postman 导入  方式， 选择刚才保存的文件路径，开始导入数据
+
+<div><img  class="doc-img"  style="width:90%"  src="./images/usage/postman-3.jpg" /></div>
+
+## HAR 数据导入
+
+<p>可用 chrome 实现录制接口数据的功能，方便开发者快速导入项目接口</p>
+
+1.打开 Chrome 浏览器开发者工具，点击 network，首次使用请先 clear 所有请求信息，确保录制功能开启（红色为开启状态）
+
+<div><img  class="doc-img" style="width:70%" src="./images/usage/chrome-1.jpg" /></div>
+
+2.操作页面实际功能，完成后点击 save as HAR with content,将数据保存到文件 xxx
+
+<div><img  class="doc-img" style="width:70%" src="./images/usage/chrome-2.jpg" /></div>
+
+3.打开 yapi 平台，进入到项目页面，点击数据管理，选择相应的分组和 har 导入  方式， 选择刚才保存的文件路径，开始导入数据
+
+<div><img class="doc-img"   style="width:50%"  src="./images/usage/chrome-3.jpg" /></div>
+
+> Tips: har 数据导入只支持 response.content.mimeType 为 application/json 类型的数据
+
+## Swagger 数据导入
+
+<p>什么是 Swagger ？</p>
+<div>[Swagger从入门到精通](https://www.gitbook.com/book/huangwenchao/swagger/details)</div>
+
+<br />
+1.生成 JSON 语言编写的 Swagger API 文档文件<div>  例如这样的数据 （<a href="http://petstore.swagger.io/v2/swagger.json" target="blank">http://petstore.swagger.io/v2/swagger.json</a>），可以将其内容复制到 JSON 文件中。</div>
+<br />
+
+> Tips: v1.3.19 版本开始支持 swagger url 导入功能
+
+2.打开 yapi 平台，进入到项目页面，点击数据管理，选择相应的分组和 swagger 导入  方式， 选择刚才的文件，开始导入数据
+
+<div><img class="doc-img"   style="width:50%"  src="./images/usage/chrome-4.jpg" /></div>
+
+<div><img class="doc-img"   style="width:90%"  src="./images/usage/chrome-5.jpg" /></div>
+
+<div><img class="doc-img"   style="width:90%"  src="./images/usage/chrome-6.jpg" /></div>
+
+## YApi 接口 JSON 数据导入
+
+该功能在 v1.3.12 版本上线，可导入在 yapi 平台导出的 json 接口数据。
+
+![](import-json-data.png)
+
+## 通过命令行导入接口数据
+
+YApi 支持通过命令行导入接口数据，他的应用场景是做自动化集成，比如配合 swagger ，接口文档前端不用维护，交由后端生成。
+
+### 使用方法
+
+第一步，确保 `yapi-cli >= 1.2.7` 版本，如果低于此版本请升级 `yapi-cli` 工具
+
+```
+npm install -g yapi-cli
+```
+
+第二步，在任意一个目录下新建配置文件 `yapi-import.json`，内容如下：
+
+```json
+{
+  "type": "swagger",
+  "token": "17fba0027f300248b804",
+  "file": "swagger.json",
+  "merge": "normal",
+  "server": "http://yapi.local.qunar.com:3000"
+}
+```
+
+`type` 是数据数据方式，目前官方只支持 swagger
+
+`token` 是项目 token，在 `项目设置 -> token` 设置获取
+
+`file` 是 swagger 接口文档文件，可使用绝对路径或 url
+
+`merge` 有三种导入方式(v1.3.23+支持) normal, good, mergin  
+1. 普通模式(normal)：不导入已存在的接口；   
+2. 智能合并(good)：已存在的接口，将合并返回数据的 response，适用于导入了 swagger 数据，保留对数据结构的改动；  
+3. 完全覆盖(mergin)：不保留旧数据，完全使用新数据，适用于接口定义完全交给后端定义， 默认为 normal
+
+`server` 是 yapi 服务器地址
+
+第三步，在`新建配置文件的当前目录`，执行下面指令
+
+```
+yapi import
+```

docs/documents/export-data.md

@@ -0,0 +1,10 @@
+# 数据导出
+为了方便开发者将接口数据分析给第三方或其他使用者，YApi 内置了方便易用的接口数据导出功能。
+
+
+## 使用教程
+
+在 项目 -> 数据管理，选择需要导出的数据方式，一共有三种导出方式，html,markdown,json。然后点击导出按钮，将会下载数据文件。
+
+![](export-data.png)
+