【YApi】接口管理平台

一、简介

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 接口文档