香蕉微波炉

API集成管理平台YAPI的搭建和使用

浅雾 Roy
2018-11-25
计算机/源码和原理
YAPI, 接口, mongoDB

随着API数量越来越多，wiki已经再也体现不出它的优势了。冗长的文档资料让人难以维护，稍微一点小改动就需要对很多地方进行修改。以前见到过的解决方案是，使用Confluence来进行接口管理和测试。但最近一位前端大佬推荐了YAPI这套API集成管理平台，上手后发现还挺不错的，不过也有一些不方便的地方，看完后可以根据需求选择。

YAPI是什么 ​

YAPI简介 ​

3d08a1899ab8a63e4cd4f24a1075890f.png YAPI是去哪儿网团队YMFE开发的一个开源项目，用于API开发，帮助开发者轻松创建、发布、维护 API，协议Apache 2.0，非常良心，先给出相关链接：

YAPI——高效、易用、功能强大的API管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。

YAPI功能特性 ​

9f7c8ab64d5ca12c00735cca48d6c5f4.png

  • 强大的Mock数据功能：前端Mock数据的福音，和Mock.js类似的语法
  • 多人可视化接口管理：多人协作（有修改历史记录）、可视化接口管理（树形结构、搜索等等）
  • 权限管理：成熟的权限管理配置
  • 兼容性：支持swagger、postman等经典接口管理工具的数据格式导入，支持markdown、json等数据格式输出
  • wiki：可以自动生成接口wiki
  • 自动化测试：其实这个功能不太好用，可以基于本地或者服务器来进行自动化测试，但目前发现只能是冒烟测试。
  • 插件机制：留有插件hook，可以二次开发
  • 支持docker部署、内网部署

YAPI普通方式部署和安装 ​

无论以哪种方式部署，都需要两个基本的环境：nodejs7.6+、mongodb2.6+。通常来说apt-get下来的版本都不满足要求，所以我们直接安装二进制包（如果有时间可以自己make源码）。

基础环境搭建 ​

首先得有下载和解压工具：

shell
apt-get install wget
apt-get install xz

nodejs官网找到二进制包的下载地址： 82b2aaf34c69142647910d039281ad94.png 用wget下载到服务器，这里选择最新稳定版10.13.0，执行解压、安装：

shell
# 下载
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

测试一下：

shell
node -v
v10.13.0

同样的方法安装mongodb：去mongodb官网，选择合适的版本，windows会是msi，Linux是tgz（用刚才加环境变量的方式安装），我们选择debian 8，是deb文件： b57a16a8cd4c1771a20218efae73e759.png

用wget下载，用dpkg安装：

shell
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：

shell
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服务器：

shell
service mongod start

用mongodb shell测试一下：

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加一个账户（密码请设置复杂点的）：

shell
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，开启登录验证：

shell
vi /etc/mongod.conf
 
#security:
auth = true

重启mongod服务：

shell
#停止当前服务
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脚本）：

shell
ps -aux|grep mongo
kill xxxxxx

安装YAPI ​

根据YAPI文档进行安装，官方推荐方式是图形界面方式：

shell
npm install -g yapi-cli --registry https://registry.npm.taobao.org
yapi server

这里我们选择命令行方式去安装：

shell
mkdir yapi
cd yapi
git clone https://github.com/YMFE/yapi.git vendors //或者下载 zip 包解压到 vendors 目录
cp vendors/config_example.json ./config.json //复制完成后请修改相关配置

然后修改这个config文件：

json
{
  "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原理、安装和使用》搭建的服务器来测试，我们把账号稍微设置得更完整： 28b980a280a8b36691701aa81975effe.png
  • baseDn、bindPassword：用于搜索用户账号的系统账号；
  • searchDn：搜索根目录；
  • searchStandard：搜索条件；
  • emailPostfix：邮箱后缀；
  • emailKey：邮箱在LDAP账号里面的属性名称；
  • usernameKey：用户显示名在LDAP账号里面的属性名称

接着执行npm依赖安装，会生成node_module目录：

shell
cd vendors
npm install --production --registry https://registry.npm.taobao.org

这一步很容易报错，这是一个bug，如果报错，请尝试：

shell
npm install --production --registry https://registry.npm.taobao.org --unsafe-perm=true --allow-root

npm依赖安装安装完成后执行yapi服务器安装：

shell
npm run install-server //安装程序会初始化数据库索引和管理员账号，管理员账号名可在 config.json 配置

这一步如果报错说Error: 初始化管理员账号 "yapiadmin" 失败，则根据打印信息去找是否是mongodb设置问题、config.json设置问题，成功的显示是这样的： abe1738ef2c642137ee30f9aa7aea940.png 完成之后启动yapi：

shell
node server/app.js

5a4c4e08beb0d23fa86c56d2584a67f2.png 然后输入公网IP:9233就可以访问啦，只要你的服务器开放了这个端口。

YAPI的使用方法 ​

基本界面介绍 ​

首页 ​

bdb10c09a6fd54a38a83c2119755098d.png

登录/注册 ​

30e50aab4f9de425f530961985a16034.png 如果配置了不让注册，1.3.x版本是点击注册后弹框提示不让注册，1.4.x版本是直接不让点击。

登录有两种方式，我们前面配置的ldap和普通的mongodb数据库登录。

我们尝试一下LDAP： 0236d9fed49f5403e80719f9a106017c.png

登录成功，然后查看一下个人信息： 3bd2a9968d36c18e37d171bebca9565e.png

是我们LDAP里面配置的字段，很棒。再尝试普通登录： 528c20eddb7d09ba53a76928f824664c.png

查看一下个人信息： 2f686b1578082a7cebcb4f2fd983e1fc.png

由于是管理员，增加了好多信息，并且普通登录支持修改用户名和密码（因为mongodb是yapi在管理）。

基本操作界面 ​

0ead581775238c12029fa8996ca921e7.png

用户管理界面（只有管理员可以看见） ​

2ed46feb9018aa15d6a323178c36c856.png

系统信息界面（只有管理员看得见） ​

a912a55c5d2f67d8dd33c56b603ca3f8.png

基本使用 ​

权限 ​

  • 角色分为超级管理员>组长>开发者>访客。
  • 目录有分组>项目。
  • 每个人都可以创建分组，但只有超级管理员可以删除分组。
  • 每个人都可以创建项目，但只有超级管理员和分组组长可以删除项目。
  • 每个人都可以创建私有分组和项目，拥有完全的管理权限。
  • 更多的权限控制可自行探索

82d994fb7a06513449dbb8e07107c15f.pngb39fce836c253460e1de0f82944070d4.png

接口编写和测试 ​

接口支持很多功能：HTTP方法、HTTPS、标签、状态等等。

请求接口支持上传文件、RAW、BODY（JSON）、query（get参数）、配置Header等，非常灵活。 93ecf8d50499671e91f5fa0ddf70be54.png

尝试运行（需要安装插件+chrome）： 0a42ce7709bc3c247ef05210e295f37e.pngb2ba6ab7ac917e172767e7a15897a9bc.png

测试一下，断言返回HTTP CODE 200： 75ca317c0b8c66d8d36cab49225cefc7.png

自动wiki ​

导出成wiki试试： 9f5940686735c0fe59df4229adfd308e.png

YAPI优缺点 ​

优点 ​

颜值高；安装简便；集成WIKI、接口编写、接口自动化测试于一体，更新非常及时；支持权限管理；支持swagger等其他API管理工具的格式数据导入；支持LDAP、SSO、CAS等登录方式；支持集群。

缺点 ​

  1. 接口返回值只能设置一个模板

有时候我们希望正确返回设置一个模板、错误返回设置一个模板，这是swagger可以做到的，而YAPI无法做到

  1. 接口模板必须复制粘贴

不像swagger解耦合一样，一处配置处处运行，例如配置“分页模板”，然后每个分页只需要引用一下就好了，修改起来只需要修改一次。而YAPI目前只有复制粘贴。

已经有人提issue了： 0f23f2c69f4b9afcf42f52f376a703f9.png

  1. 测试功能太鸡肋

只能做冒烟测试，给数据、返回期望数据。无法编写测试逻辑（如果返回XX则跳到XX），无法返回多个值（如果200则XX，如果404则XX），也就无法编写单元测试了。

其他 ​

nginx代理配置 ​

因为YAPI是基于websocket的，所以如果用了nginx反向代理转发，可以这样配置：

yaml
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;
    }
}

然后执行：

shell
nginx -t -c [配置文件]
nginx -s reload

YAPI7天备份脚本 ​

shell
#!/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每天周期运行这个脚本：

shell
crontab -e
0 2 * * * /home/yapi/backup/backup.sh
转载请注明出处：https://bananaoven.com/articles/222.html | 香蕉微波炉
分享许可方式：知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议
重大发现：转载注明原文网址的同学刚买了彩票就中奖，刚写完代码就跑通，刚转身就遇到了真爱。
你可能还会喜欢
YAPI Docker集成2020/02/05
YAPI Docker集成2020/02/05
Java AES密钥长度超过16报错的问题2020/03/28
Java AES密钥长度超过16报错的问题2020/03/28
在ubuntu16.04上安装nvidia驱动2018/03/21
在ubuntu16.04上安装nvidia驱动2018/03/21
摩尔斯电码对照表2017/12/02
摩尔斯电码对照表2017/12/02
香蕉微波炉 © 2017-2025 · 浅雾Roy
打赏一下
支付宝微信
博客UI
BWBUI 3.0
备案信息
粤ICP备2023095572号 粤公网安备44030602007943号
联系我
发邮件 bewindoweb1995@foxmail.com GitHub BEWINDOWEB