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
