前言
随着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、基础环境搭建
首先得有下载和解压工具:
apt-get install wget
apt-get install xz
nodejs官网找到二进制包的下载地址:
用wget下载到服务器,这里选择最新稳定版10.13.0,执行解压、安装:
# 下载
wget https://nodejs.org/dist/v10.13.0/node-v10.13.0-linux-x64.tar.xz
# 解压
xz -d node-v10.13.0-linux-x64.tar.xz
tar -xvf node-v10.13.0-linux-x64.tar
# 移动到合适地方
mv node-v10.13.0-linux-x64 /usr/local/node-v10.13.0-linux-x64
# 添加环境变量
vi ~/.bashrc
export PATH=$PATH:/usr/local/node-v10.13.0-linux-x64/bin
source ~/.bashrc
测试一下:
node -v
v10.13.0
同样的方法安装mongodb:去mongodb官网,选择合适的版本,windows会是msi,Linux是tgz(用刚才加环境变量的方式安装),我们选择debian 8,是deb文件:
用wget下载,用dpkg安装:
wget https://repo.mongodb.org/apt/debian/dists/jessie/mongodb-org/4.0/main/binary-amd64/mongodb-org-server_4.0.4_amd64.deb
sudo dpkg -i mongodb-org-server_4.0.4_amd64.deb
但下载过于缓慢(5kb/s),所以可以使用阿里镜像,选择适合自己系统的,这里是debian 8 amd64:
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
dpkg -i mongodb-org-server_4.0.4_amd64.deb
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
dpkg -i mongodb-org-shell_4.0.4_amd64.deb
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
dpkg -i mongodb-org-tools_4.0.4_amd64.deb
顺手装了一个shell(如果不装shell,只能启动服务,不能使用mongo命令作为客户端去连接mongodb服务器),再装一个tools(包含mongodump等备份工具)只花了1.2秒。
启动mongodb服务器:
service mongod start
用mongodb shell测试一下:
mongo
MongoDB shell version v4.0.4
connecting to: mongodb://127.0.0.1:27017
Implicit session: session { "id" : UUID("2558d8c3-4873-4c39-8a77-3a5a41d067b5") }
MongoDB server version: 4.0.4
Welcome to the MongoDB shell.
mongodb默认是谁都可以进的(不像mysql有root用户),所以我们需要给mongodb加一个账户(密码请设置复杂点的):
mongo
# 创建数据库,名字必须是yapi
use yapi
# 增加一个yapi管理员账户
db.createUser({
user: "yapidba",
pwd: "123456",
roles:[
{
role:"readWrite",
db:"yapi"
}
]
})
# 进入admin数据库
use admin
# 增加一个mongodb超级管理员账户
db.createUser({
user: "mongoadmin",
pwd: "123456",
roles:[
{
role:"userAdminAnyDatabase",
db:"admin"
}
]
})
CTRL+C退出mongo,开启登录验证:
vi /etc/mongod.conf
#security:
auth = true
重启mongod服务:
#停止当前服务
service mongod stop
# 创建/data/db
mkdir /data
mkdir /data/db
# 手工后台启动mongod
mongod --auth --fork --logpath=/var/log/mongodb/mongod.log
# 完整的语句是
mongod --auth --dbpath=[你的db数据文件存放路径] --fork --logpath=[你的日志存放路径]
注意,手工启动的话只能杀进程来退出(你也可以自己编写service脚本):
ps -aux|grep mongo
kill xxxxxx
2、安装YAPI
根据YAPI文档进行安装,官方推荐方式是图形界面方式:
npm install -g yapi-cli --registry https://registry.npm.taobao.org
yapi server
这里我们选择命令行方式去安装:
mkdir yapi
cd yapi
git clone https://github.com/YMFE/yapi.git vendors //或者下载 zip 包解压到 vendors 目录
cp vendors/config_example.json ./config.json //复制完成后请修改相关配置
然后修改这个config文件:
{
"port": "9233",
"adminAccount": "yapiadmin@bewindoweb.com",
"closeRegister":true,
"db": {
"servername": "127.0.0.1",
"DATABASE": "yapi",
"port": 27017,
"user": "yapidba",
"pass": "123456",
"authSource": ""
},
"mail": {
"enable": false,
"host": "smtp.163.com",
"port": 465,
"from": "***@163.com",
"auth": {
"user": "***@163.com",
"pass": "*****"
}
},
"ldapLogin":{
"enable":true,
"server":"ldap://localhost:389",
"baseDn":"cn=Manager,dc=bewindoweb,dc=com",
"bindPassword":"123456",
"searchDn":"dc=bewindoweb,dc=com",
"searchStandard":"mail",
"emailPostfix":"@bewindoweb.com",
"emailKey":"mail",
"usernameKey":"description"
}
}
(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
目录:
cd vendors
npm install --production --registry https://registry.npm.taobao.org
这一步很容易报错,这是一个bug,如果报错,请尝试:
npm install --production --registry https://registry.npm.taobao.org --unsafe-perm=true --allow-root
npm依赖安装安装完成后执行yapi服务器安装:
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反向代理转发,可以这样配置:
server{
listen 8081;
server_name yapi.bewindoweb.com;
location / {
proxy_buffers 8 32k;
proxy_buffer_size 64k;
# websocket
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
client_max_body_size 500m;
proxy_pass http://localhost:9233;
}
}
然后执行:
nginx -t -c [配置文件]
nginx -s reload
YAPI7天备份脚本
#!/bin/sh
# args
basepath=$(cd `dirname $0`; pwd)
datapath=$basepath
olddatapath=$basepath'/backupdata7days'
mdpath="/usr/bin/mongodump"
databasename="yapi"
user="yapidba"
password="123456"
hostname="localhost"
port="27017"
# move old data to olddatapath
if [ "`ls -A ${datapath}`" != "" ];then
mv ${datapath}'/'*${databasename}* ${olddatapath} 2>/dev/null
fi
# gen new backup
now=$(date +"%Y-%m-%d")
file=${datapath}'/'${databasename}-$now
${mdpath} -h${hostname}:${port} -u${user} -p${password} -d${databasename} -o${file}
#echo ${mdpath} -h${hostname}:${port} -u${user} -p${password} -d${databasename} -o${file}
# clean up over 7 days
sevendays=$(date -d -7day +"%Y-%m-%d")
if [ -d ${olddatapath}'/'$databasename'-'$sevendays ];then
rm -rf ${olddatapath}'/'$databasename'-'$sevendays
fi
然后使用crontab每天周期运行这个脚本:
crontab -e
0 2 * * * /home/yapi/backup/backup.sh