一、简介
YApi 是一个用于前后端开发团队协作的 API 管理平台,帮助团队更加高效地进行 API 接口的设计、测试、文档管理和版本控制等工作。
YApi 主要功能:
- API 设计和管理:提供 API 设计和文档生成工具,使开发者能够轻松创建、修改和维护 API 接口。
- Mock 支持:YApi 支持生成 Mock 服务,可以在后端接口尚未完成的情况下,前端开发人员也能基于模拟的数据进行开发工作。
- 接口调试:提供内置的调试工具,方便开发者直接在平台上测试 API,查看请求和响应数据。
- 版本控制:YApi 支持 API 的版本管理,有助于维护不同版本的 API,方便回滚或维护长期支持的版本。
- 团队协作:通过权限管理,可以实现团队成员之间的协作,比如 API 的共享、评论等功能,提高团队沟通效率。
- 插件扩展:YApi 支持插件系统,可以根据需要安装不同的插件来增强功能,比如导出导入、环境切换等
- 自动化测试:提供接口自动化测试功能,帮助团队在发布前发现和解决问题。
- 多项目支持:支持管理多个项目,适合大型团队和复杂项目的需求。
二、部署
1、环境要求
- nodejs(7.6+)
- mongodb(2.6+)
2、部署
方式一、可视化部署[推荐]
执行 yapi server 启动可视化部署程序,输入相应的配置和点击开始部署,就能完成整个网站的部署。部署完成之后,可按照提示信息,执行 node/{网站路径/server/app.js} 启动服务器。在浏览器打开指定url, 点击登录输入您刚才设置的管理员邮箱,默认密码(ymfe.org) 登录系统(默认密码可在个人中心修改)。
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
# 复制完成后请修改相关配置
cp vendors/config_example.json ./config.json
cd vendors
# 安装程序会初始化数据库索引和管理员账号,管理员账号名可在 config.json 配置
npm install --production --registry https://registry.npm.taobao.org
npm run install-server
# 启动服务器,访问 127.0.0.1:{config.json配置的端口},初次运行会有个编译的过程,请耐心等候
node server/app.js
安装后的目录结构如下:
|-- config.json
|-- init.lock
|-- log
`-- vendors
|-- CHANGELOG.md
|-- LICENSE
|-- README.md
|-- client
|-- common
|-- config_example.json
|-- doc
|-- exts
|-- nodemon.json
|-- npm-debug.log
|-- package.json
|-- plugin.json
|-- server
|-- static
|-- test
|-- webpack.alias.js
|-- yapi-base-flow.jpg
|-- ydocfile.js
`-- ykit.config.js
3、升级
升级项目版本是非常容易的,并且不会影响已有的项目数据,只会同步 vendors 目录下的源码文件。
#
cd {项目目录}
# 查看版本号列表
yapi ls
# 查看版本号列表
yapi update
# 升级到指定版本
yapi update -v v1.1.0
4、配置邮箱
打开项目目录 config.json 文件,新增 mail 配置, 替换默认的邮箱配置
{
"port": "*****",
"adminAccount": "********",
"db": {...},
"mail": {
"enable": true,
"host": "smtp.163.com", //邮箱服务器
"port": 465, //端口
"from": "***@163.com", //发送人邮箱
"auth": {
"user": "***@163.com", //邮箱服务器账号
"pass": "*****" //邮箱服务器密码
}
}
}
如何申请STMP服务器账号和密码可以参考下面的教程:如何开通电子邮箱的SMTP功能
5、配置LDAP登录
打开项目目录 config.json 文件,添加如下字段:
{
"port": "*****",
"adminAccount": "********",
"db": {...},
"mail": {...},
"ldapLogin": {
"enable": true,
"server": "ldap://l-ldapt1.com",
"baseDn": "CN=Admin,CN=Users,DC=test,DC=com",
"bindPassword": "password123",
"searchDn": "OU=UserContainer,DC=test,DC=com",
"searchStandard": "mail", // 自定义格式: "searchStandard": "&(objectClass=user)(cn=%s)"
"emailPostfix": "@163.com",
"emailKey": "mail",
"usernameKey": "name"
}
}
这里面的配置项含义如下:
- enable 表示是否配置 LDAP 登录,true(支持 LDAP登录 )/false(不支持LDAP登录);
- server LDAP 服务器地址,前面需要加上 ldap:// 前缀,也可以是 ldaps:// 表示是通过 SSL 连接;
- baseDn LDAP 服务器的登录用户名,必须是从根结点到用户节点的全路径(非必须);
- bindPassword 登录该 LDAP 服务器的密码(非必须);
- searchDn 查询用户数据的路径,类似数据库中的一张表的地址,注意这里也必须是全路径;
- searchStandard 查询条件,这里是 mail 表示查询用户信息是通过邮箱信息来查询的。注意,该字段信息与LDAP数据库存储数据的字段相对应,如果如果存储用户邮箱信息的字段是 email, 这里就需要修改成 email.(1.3.18+支持)自定义filter表达式,基本形式为:&(objectClass=user)(cn=%s), 其中%s会被username替换
- emailPostfix 登陆邮箱后缀(非必须)
- emailKey: ldap数据库存放邮箱信息的字段(v1.3.21 新增 非必须)
- usernameKey: ldap数据库存放用户名信息的字段(v1.3.21 新增 非必须)
重启服务器后,可以在登录页看到如下画面,说明 ladp 配置成功
6、禁止注册
在 config.json 添加 closeRegister:true 配置项,就可以禁止用户注册 yapi 平台,修改完成后,请重启 yapi 服务器。
{
"port": "*****",
"closeRegister":true
}
7、版本通知
(v1.3.19+ 增加)在 config.json 添加 “versionNotify”: true 配置项,就可以开启版本通知功能,默认为 false,修改完成后,请重启 yapi 服务器。
{
"port": "******",
"adminAccount": "*****",
"versionNotify": true
}
如何配置mongodb集群
请升级到 yapi >= 1.4.0以上版本,然后在 config.json db项,配置 connectString:
{
"port": "***",
"db": {
"connectString": "mongodb://127.0.0.100:8418,127.0.0.101:8418,127.0.0.102:8418/yapidb?slaveOk=true",
"user": "******",
"pass": "******"
},
}
详细配置参考: wiki
十、参考资料
- YApi 教程
- YApi 内网部署
- YApi 接口文档