API集成管理平台YAPI的搭建和使用
前言
隨著API數量越來越多,wiki已經再也體現不出它的優勢了。冗長的文檔資料讓人難以維護,稍微一點小改動就需要對很多地方進行修改。以前見到過的解決方案是,使用Confluence來進行接口管理和測試。但最近一位前端大佬推薦了YAPI這套API集成管理平臺,上手后發現還挺不錯的,不過也有一些不方便的地方,看完后可以根據需求選擇。
一、YAPI是什么
YAPI簡介
YAPI是去哪兒網團隊YMFE開發的一個開源項目,用于API開發,幫助開發者輕松創建、發布、維護 API,協議Apache 2.0,非常良心,先給出相關鏈接:
(1)去哪兒網:和攜程類似的訂票網站
(2)YAPI官網:YAPI的簡介
(3)YAPIgithub倉庫:YAPI的源碼
(4)YAPI使用文檔:YAPI安裝手冊、使用方法等
(5)官方交流QQ群:644642474(2018年11月18日有效)
官方的宣傳:
YAPI——高效、易用、功能強大的API管理平臺,旨在為開發、產品、測試人員提供更優雅的接口管理服務。
YAPI功能特性
(1)強大的Mock數據功能:前端Mock數據的福音,和Mock.js類似的語法
(2)多人可視化接口管理:多人協作(有修改歷史記錄)、可視化接口管理(樹形結構、搜索等等)
(3)權限管理:成熟的權限管理配置
(4)兼容性:支持swagger、postman等經典接口管理工具的數據格式導入,支持markdown、json等數據格式輸出
(5)wiki:可以自動生成接口wiki
(6)自動化測試:其實這個功能不太好用,可以基于本地或者服務器來進行自動化測試,但目前發現只能是冒煙測試。
(7)插件機制:留有插件hook,可以二次開發
(8)支持docker部署、內網部署
二、YAPI普通方式部署和安裝
無論以哪種方式部署,都需要兩個基本的環境:nodejs7.6+、mongodb2.6+。通常來說apt-get下來的版本都不滿足要求,所以我們直接安裝二進制包(如果有時間可以自己make源碼)。
1、基礎環境搭建
首先得有下載和解壓工具:
1.apt-get install wget 2.apt-get install xz
nodejs官網找到二進制包的下載地址:
用wget下載到服務器,這里選擇最新穩定版10.13.0,執行解壓、安裝:
1 # 下載 2 wget https://nodejs.org/dist/v10.13.0/node-v10.13.0-linux-x64.tar.xz 3 # 解壓 4 xz -d node-v10.13.0-linux-x64.tar.xz 5 tar -xvf node-v10.13.0-linux-x64.tar 6 # 移動到合適地方 7 mv node-v10.13.0-linux-x64 /usr/local/node-v10.13.0-linux-x64 8 # 添加環境變量 9 vi ~/.bashrc 10 export PATH=$PATH:/usr/local/node-v10.13.0-linux-x64/bin 11 source ~/.bashrc
測試一下:
1 node -v 2 v10.13.0
同樣的方法安裝mongodb:去mongodb官網,選擇合適的版本,windows會是msi,Linux是tgz(用剛才加環境變量的方式安裝),我們選擇debian 8,是deb文件:
用wget下載,用dpkg安裝:
1 wget https://repo.mongodb.org/apt/debian/dists/jessie/mongodb-org/4.0/main/binary-amd64/mongodb-org-server_4.0.4_amd64.deb 2 sudo dpkg -i mongodb-org-server_4.0.4_amd64.deb
但下載過于緩慢(5kb/s),所以可以使用阿里鏡像,選擇適合自己系統的,這里是debian 8 amd64:
1 wget http://mirrors.aliyun.com/mongodb/apt/debian/dists/jessie/mongodb-org/4.0/main/binary-amd64/mongodb-org-server_4.0.4_amd64.deb 2 dpkg -i mongodb-org-server_4.0.4_amd64.deb 3 wget http://mirrors.aliyun.com/mongodb/apt/debian/dists/jessie/mongodb-org/4.0/main/binary-amd64/mongodb-org-shell_4.0.4_amd64.deb 4 dpkg -i mongodb-org-shell_4.0.4_amd64.deb 5 wget http://mirrors.aliyun.com/mongodb/apt/debian/dists/jessie/mongodb-org/4.0/main/binary-amd64/mongodb-org-tools_4.0.4_amd64.deb 6 dpkg -i mongodb-org-tools_4.0.4_amd64.deb
順手裝了一個shell(如果不裝shell,只能啟動服務,不能使用mongo命令作為客戶端去連接mongodb服務器),再裝一個tools(包含mongodump等備份工具)只花了1.2秒。
啟動mongodb服務器:
service mongod start
用mongodb shell測試一下:
1 mongo
2  
3 MongoDB shell version v4.0.4
4 connecting to: mongodb://127.0.0.1:27017
5 Implicit session: session { "id" : UUID("2558d8c3-4873-4c39-8a77-3a5a41d067b5") }
6 MongoDB server version: 4.0.4
7 Welcome to the MongoDB shell.
mongodb默認是誰都可以進的(不像mysql有root用戶),所以我們需要給mongodb加一個賬戶(密碼請設置復雜點的):
 1 mongo
 2 # 創建數據庫,名字必須是yapi
 3 use yapi
 4 # 增加一個yapi管理員賬戶
 5 db.createUser({
 6 user: "yapidba",
 7 pwd: "123456",
 8 roles:[
 9 {
10 role:"readWrite",
11 db:"yapi"
12 }
13 ]
14 })
15 # 進入admin數據庫
16 use admin
17 # 增加一個mongodb超級管理員賬戶
18 db.createUser({
19 user: "mongoadmin",
20 pwd: "123456",
21 roles:[
22 {
23 role:"userAdminAnyDatabase",
24 db:"admin"
25 }
26 ]
27 })
CTRL+C退出mongo,開啟登錄驗證:
1 vi /etc/mongod.conf 2 3 #security: 4 auth = true 5 重啟mongod服務:
1 #停止當前服務 2 service mongod stop 3 # 創建/data/db 4 mkdir /data 5 mkdir /data/db 6 # 手工后臺啟動mongod 7 mongod --auth --fork --logpath=/var/log/mongodb/mongod.log 8 # 完整的語句是 9 mongod --auth --dbpath=[你的db數據文件存放路徑] --fork --logpath=[你的日志存放路徑]
注意,手工啟動的話只能殺進程來退出(你也可以自己編寫service腳本):
1 ps -aux|grep mongo 2 kill xxxxxx
2、安裝YAPI
根據YAPI文檔進行安裝,官方推薦方式是圖形界面方式:
1 npm install -g yapi-cli --registry https://registry.npm.taobao.org 2 yapi server
這里我們選擇命令行方式去安裝:
1 mkdir yapi 2 cd yapi 3 git clone https://github.com/YMFE/yapi.git vendors //或者下載 zip 包解壓到 vendors 目錄 4 cp vendors/config_example.json ./config.json //復制完成后請修改相關配置
然后修改這個config文件:
 1 {
 2 "port": "9233",
 3 "adminAccount": "yapiadmin@bewindoweb.com",
 4 "closeRegister":true,
 5 "db": {
 6 "servername": "127.0.0.1",
 7 "DATABASE": "yapi",
 8 "port": 27017,
 9 "user": "yapidba",
10 "pass": "123456",
11 "authSource": ""
12 },
13 "mail": {
14 "enable": false,
15 "host": "smtp.163.com",
16 "port": 465,
17 "from": "***@163.com",
18 "auth": {
19 "user": "***@163.com",
20 "pass": "*****"
21 }
22 },
23 "ldapLogin":{
24 "enable":true,
25 "server":"ldap://localhost:389",
26 "baseDn":"cn=Manager,dc=bewindoweb,dc=com",
27 "bindPassword":"123456",
28 "searchDn":"dc=bewindoweb,dc=com",
29 "searchStandard":"mail",
30 "emailPostfix":"@bewindoweb.com",
31 "emailKey":"mail",
32 "usernameKey":"description"
33 }
34 }
(1)adminAccount:和mongodb無關,是yapi登錄使用的賬號名,后綴必須是@,密碼默認ymfe.org
(2)closeRegister:禁止注冊
(3)user/pass:剛才mongodb設置的yapi的用戶名和密碼
(4)mail:暫時關閉,設置為false
(5)ldapLogin:增加ldap登錄方式,利用前面《openLDAP原理、安裝和使用》搭建的服務器來測試,我們把賬號稍微設置得更完整:
baseDn、bindPassword:用于搜索用戶賬號的系統賬號;
searchDn:搜索根目錄;
searchStandard:搜索條件;
emailPostfix:郵箱后綴;
emailKey:郵箱在LDAP賬號里面的屬性名稱;
usernameKey:用戶顯示名在LDAP賬號里面的屬性名稱
接著執行npm依賴安裝,會生成node_module目錄:
1 cd vendors 2 npm install --production --registry https://registry.npm.taobao.org
這一步很容易報錯,這是一個bug,如果報錯,請嘗試:
1 npm install --production --registry https://registry.npm.taobao.org --unsafe-perm=true --allow-root
npm依賴安裝安裝完成后執行yapi服務器安裝:
1 npm run install-server //安裝程序會初始化數據庫索引和管理員賬號,管理員賬號名可在 config.json 配置
這一步如果報錯說Error: 初始化管理員賬號 "yapiadmin" 失敗,則根據打印信息去找是否是mongodb設置問題、config.json設置問題,成功的顯示是這樣的:
完成之后啟動yapi:
node server/app.js
然后輸入公網IP:9233就可以訪問啦,只要你的服務器開放了這個端口。
三、YAPI的使用方法
1、基本界面介紹
【首頁】
【登錄/注冊】
如果配置了不讓注冊,1.3.x版本是點擊注冊后彈框提示不讓注冊,1.4.x版本是直接不讓點擊。
登錄有兩種方式,我們前面配置的ldap和普通的mongodb數據庫登錄。
我們嘗試一下LDAP:
登錄成功,然后查看一下個人信息:
是我們LDAP里面配置的字段,很棒。再嘗試普通登錄:
查看一下個人信息:
由于是管理員,增加了好多信息,并且普通登錄支持修改用戶名和密碼(因為mongodb是yapi在管理)。
【基本操作界面】
【用戶管理界面】(只有管理員可以看見)
【系統信息界面】(只有管理員看得見)
2、基本使用
【權限】
角色分為超級管理員>組長>開發者>訪客。
目錄有分組>項目。
每個人都可以創建分組,但只有超級管理員可以刪除分組。
每個人都可以創建項目,但只有超級管理員和分組組長可以刪除項目。
每個人都可以創建私有分組和項目,擁有完全的管理權限。
更多的權限控制可自行探索:
【接口編寫和測試】
接口支持很多功能:HTTP方法、HTTPS、標簽、狀態等等。
請求接口支持上傳文件、RAW、BODY(JSON)、query(get參數)、配置Header等,非常靈活。
嘗試運行(需要安裝插件+chrome):
測試一下,斷言返回HTTP CODE 200:
【自動wiki】
導出成wiki試試:
四、YAPI優缺點
優點
顏值高;安裝簡便;集成WIKI、接口編寫、接口自動化測試于一體,更新非常及時;支持權限管理;支持swagger等其他API管理工具的格式數據導入;支持LDAP、SSO、CAS等登錄方式;支持集群。
缺點
(1)接口返回值只能設置一個模板
有時候我們希望正確返回設置一個模板、錯誤返回設置一個模板,這是swagger可以做到的,而YAPI無法做到
(2)接口模板必須復制粘貼
不像swagger解耦合一樣,一處配置處處運行,例如配置“分頁模板”,然后每個分頁只需要引用一下就好了,修改起來只需要修改一次。而YAPI目前只有復制粘貼。
已經有人提issue了:
(3)測試功能太雞肋
只能做冒煙測試,給數據、返回期望數據。無法編寫測試邏輯(如果返回XX則跳到XX),無法返回多個值(如果200則XX,如果404則XX),也就無法編寫單元測試了。
五、其他
nginx代理配置
因為YAPI是基于websocket的,所以如果用了nginx反向代理轉發,可以這樣配置:
 1 server{
 2 listen 8081;
 3 server_name yapi.bewindoweb.com;
 4 location / {
 5 proxy_buffers 8 32k;
 6 proxy_buffer_size 64k;
 7 # websocket
 8 proxy_http_version 1.1;
 9 proxy_set_header Upgrade $http_upgrade;
10 proxy_set_header Connection "upgrade";
11  
12 client_max_body_size 500m;
13 proxy_pass http://localhost:9233;
14 }
15 }
16 然后執行:
17 
18 nginx -t -c [配置文件]
19 nginx -s reload
20 YAPI7天備份腳本
21 
22 #!/bin/sh
23 # args
24 basepath=$(cd `dirname $0`; pwd)
25 datapath=$basepath
26 olddatapath=$basepath'/backupdata7days'
27 mdpath="/usr/bin/mongodump"
28 databasename="yapi"
29 user="yapidba"
30 password="123456"
31 hostname="localhost"
32 port="27017"
33  
34 # move old data to olddatapath
35 if [ "`ls -A ${datapath}`" != "" ];then
36 mv ${datapath}'/'*${databasename}* ${olddatapath} 2>/dev/null
37 fi
38  
39 # gen new backup
40 now=$(date +"%Y-%m-%d")
41 file=${datapath}'/'${databasename}-$now
42 ${mdpath} -h${hostname}:${port} -u${user} -p${password} -d${databasename} -o${file}
43 #echo ${mdpath} -h${hostname}:${port} -u${user} -p${password} -d${databasename} -o${file}
44  
45 # clean up over 7 days
46 sevendays=$(date -d -7day +"%Y-%m-%d")
47 if [ -d ${olddatapath}'/'$databasename'-'$sevendays ];then
48 rm -rf ${olddatapath}'/'$databasename'-'$sevendays
49 fi
50 然后使用crontab每天周期運行這個腳本:
51 
52 crontab -e
53 0 2 * * * /home/yapi/backup/backup.sh
                            總結
以上是生活随笔為你收集整理的API集成管理平台YAPI的搭建和使用的全部內容,希望文章能夠幫你解決所遇到的問題。
 
                            
                        - 上一篇: 机器学习之路:python支持向量机回归
- 下一篇: 第二章 氨基酸序列的进化演变
