為方便和前端, 節(jié)省溝通成本, 編寫接口文檔非常有比較
使用過swagger, 覺得入侵性太大. POST又感覺和項目結(jié)合的不太緊密. 所以一直在尋找新的接口閱讀/生成/測試工具. 下面介紹一下YApi.
如何創(chuàng)建接口？
把大象裝進冰箱分幾步觅廓？三步：把冰箱門打開十办，把大象裝進去廓块，關(guān)門，搞定~
新建接口分幾步中姜？也是三步：
搞定~
接口設(shè)置
進入項目頁宏粤，可以看到項目下的所有接口删壮，需要注意的是铐拐，YApi有 接口集合 和 測試集合 兩個概念饰迹。
-
接口集合將接口進行分類，使接口結(jié)構(gòu)更清晰余舶，一個接口只能屬于一個集合，且不允許與其他接口重名锹淌。 -
測試集合為了方便我們測試接口匿值，測試集合將若干接口組合在一起，在這里一個接口可以屬于不同集合赂摆。
接口配置
新建接口 后挟憔，點擊新添加的接口，右側(cè)可以看到接口的預覽信息烟号，點擊右側(cè)的 編輯 Tab項進入編輯面板绊谭。
在該面板中你可以看到接口的基本信息(接口名稱、分類汪拥、路徑)达传，除此以外，你還可以完善以下接口信息：
基本設(shè)置
- 接口路徑：可以更改 HTTP 請求方式迫筑，并且支持 restful 動態(tài)路由宪赶，例如 /api/{id}/{name}, id和name是動態(tài)參數(shù)
- 選擇分類：可以更改接口所在分類
- 狀態(tài)：用于標識接口是否開發(fā)完成。
- Tag：用于標識接口tag信息（v1.3.23+）,在接口list頁可以根據(jù)tag過濾接口
請求參數(shù)設(shè)置
- Query參數(shù)： 接口 url 的查詢字符串脯燃，點擊『添加Query參數(shù)』按鈕來添加參數(shù)搂妻，可以通過拖動來交換參數(shù)位置
- 請求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
返回數(shù)據(jù)設(shè)置
- 返回數(shù)據(jù)分為
json&raw兩種形式〔咕基于 mockjs （具體使用方法詳見Mock 介紹）和 json5涤妒，使用注釋方式寫參數(shù)說明。 為了方便數(shù)據(jù)編寫可以按F9來使用全局編輯 - 選擇json-schema 則進入了 json 結(jié)構(gòu)可視化編輯器形式, 數(shù)據(jù)以 json schema 格式解析 快速入門 Json Schema 赚哗。
備注 & 其他
- 接口描述: 用簡短的文字描述接口的作用她紫。
- 郵件通知：開啟后將此次接口的改動以郵件的形式發(fā)送至項目組所有成員和關(guān)注該項目的成員（郵件默認情況下自動開啟）
- 開放接口：默認為關(guān)閉狀態(tài)硅堆，用戶可以在 數(shù)據(jù)導出 時選擇只導出公開接口
接口運行
接口運行功能，是用來測試真實接口的贿讹，類似『Postman』的功能渐逃。
點擊運行 tab ,可進入到接口測試頁面，首先安裝『chrome crossRequest』擴展民褂，才可正常使用此功能茄菊。
點擊保存按鈕可把當前接口保存到測試集，方便下次調(diào)試赊堪。
安裝完插件記得刷新頁面
接口返回數(shù)據(jù)驗證
版本 v1.3.22 新增返回數(shù)據(jù)驗證功能面殖， 如果接口的返回數(shù)據(jù)格式為json schema 在接口運行時會對接口返回數(shù)據(jù)和定義數(shù)據(jù)格式進行校驗
Mock介紹
YApi的 Mock 功能可以根據(jù)用戶的輸入接口信息如協(xié)議、URL哭廉、接口名脊僚、請求頭、請求參數(shù)遵绰、返回數(shù)據(jù)（返回數(shù)據(jù)）生成 Mock 接口辽幌，這些接口會自動生成模擬數(shù)據(jù)，創(chuàng)建者可以自由構(gòu)造需要的數(shù)據(jù)椿访。
mock地址解析：YApi平臺網(wǎng)址 + mock + 您的項目id + 接口實際請求path
假設(shè)你 YApi 的部署地址為：http://yapi.xxx.com 然后用這個地址作為示例
mockd 地址： http://yapi.xxx.com/mock/29/api/hackathon/login
注：項目 id 可以在項目設(shè)置里查看到
定義 mock 數(shù)據(jù)示例
項目 -> 接口編輯 -> 返回數(shù)據(jù)設(shè)置
返回數(shù)據(jù)設(shè)置有兩種方式乌企，最新版本默認是基于 json+注釋 的方式，另外一種是基于 json-schema 定義數(shù)據(jù)結(jié)構(gòu),請根據(jù)實際情況靈活選擇使用成玫。
方式1. mockjs
原理
基于 mockjs加酵，跟 Mockjs 區(qū)別是 yapi 基于 json + 注釋 定義 mock 數(shù)據(jù)，無法使用 mockjs 原有的函數(shù)功能哭当。
- 正則表達式需要基于 rule 書寫虽画，示例如下：
{
"name|regexp": "[a-z0-9_]+?",
"type|regexp": "json|text|xml"
}
- 支持替換請求的 query, body 參數(shù)
{
"name": "${query.name}", //請求的url是/path?name=xiaoming, 返回的name字段是xiaoming
"type": "${body.type}", //請求的requestBody type=1,返回的type字段是1
}
- 示例
/**
* 這是一個接口返回數(shù)據(jù)示例
*/
{
"errcode": 0,
"errmsg": "@word",
"data": {
"id": "@id", //@id 隨機生成 id
"name": "@name" //@name 隨機生成用戶名
}
}
詳細使用文檔請查看：Mockjs 官網(wǎng)
方式2. json-schema
開啟 json-schema 功能后，根據(jù) json-schema 定義的數(shù)據(jù)結(jié)構(gòu)荣病，生成隨機數(shù)據(jù)码撰。
如何生成隨機的郵箱或 ip(該方法在v1.3.22之后不再適用)？
點擊高級設(shè)置个盆，選擇 format 選項脖岛，比如選擇 email 則該字段生成隨機郵箱字符串。
集成 mockjs
基本書寫方式為 mock 的數(shù)據(jù)占位符@xxx, 具體字段詳見Mockjs 官網(wǎng)
如果不是以@字符開頭的話或者匹配不到Mockjs中的占位符就會直接生成輸入的值
如何使用 Mock
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) //返回上圖預覽部分的數(shù)據(jù)
})
2 基于本地服務器反向代理
優(yōu)點:不用修改項目代碼
2.1 基于 nginx 反向代理
location /baseapi
{
proxy_pass http://yapi.xxx.com/mock/2817/baseapi; #baseapi后面沒有"/"
}
2.1 基于 Charles 代理
點擊 Charles 工具欄下的 tools >> Rewrite Settings 填寫如下信息：
mock請求嚴格模式
版本 v1.3.22 新增 mock 接口請求字段參數(shù)驗證功能柴梆，具體使用方法如下：
打開 項目 -> 設(shè)置 開啟 mock 嚴格模式
-
針對 query, form 中設(shè)置的必須字段會進行必填校驗 image
針對 req_body_type 是json schema 格式的數(shù)據(jù)進行校驗
來源
文章全文完全來自 YApi-教程.
https://hellosean1025.github.io/yapi/documents/index.html
