一、介绍

YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

二、特性

特性：

基于 Json5 和 Mockjs 定义接口返回数据的结构和文档，效率提升多倍

扁平化权限设计，即保证了大型企业级项目的管理，又保证了易用性

类似 postman 的接口调试

自动化测试, 支持对 Response 断言

MockServer 除支持普通的随机 mock 外，还增加了 Mock 期望功能，根据设置的请求过滤规则，返回期望数据

支持 postman, json, swagger 数据导入

三、环境部署

环境要求

• nodejs（7.6+)
• mongodb（2.6+）
• git

使用我们提供的 yapi-cli 工具，部署 YApi 平台是非常容易的。

执行 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 //或者下载 zip 包解压到 vendors 目录（clone 整个仓库大概 140+ M，可以通过 `git clone --depth=1 https://github.com/YMFE/yapi.git vendors` 命令减少，大概 10+ M）
cp vendors/config_example.json ./config.json //复制完成后请修改相关配置
cd vendors
npm install --production --registry https://registry.npm.taobao.org
npm run install-server //安装程序会初始化数据库索引和管理员账号，管理员账号名可在 config.json 配置
node server/app.js //启动服务器后，请访问 127.0.0.1:{config.json配置的端口}，初次运行会有个编译的过程，请耐心等候

数据库&通知邮箱&LDAP配置：

/var/www/html/yapi/config.json 打开配置文件

{
  #端口
  "port": "3000",
  #禁止用户注册
  "closeRegister":true,
  "adminAccount": "admin@admin.com",
  "timeout":120000,
  #数据库Mongodb配置
  "db": {
    "servername": "10.2.1.3",
    "DATABASE": "yapi",
    "port": 27017,
    "user": "",
    "pass": "",
    "authSource": ""
  },
  #邮箱配置，如果有接口变动后会有邮件通知
  "mail": {
    "enable": true,
    "host": "smtp.exmail.qq.com",
    "port": 465,
    "from": "notice@mail.com",
    "encryption": "ssl",
    "auth": {
      "user": "notice@mail.com",
      "pass": "devtest2024"
    }
  },
  #ldap配置，可直接与公司现有用户体系打通
 "ldapLogin": {
      "enable": true,
      "server": "ldap://10.2.1.4:389",
      "baseDn":"uid=ciread,ou=people,dc=bacicweb,dc=com",
      "bindPassword":"Admin123",
      "searchDn":"dc=bacicweb,dc=com",
      "searchStandard": "mail"
   }
}

官网安装：内网部署

官网文档

PM2实用入门指南

Host配置指定内网域名访问

Nginx配置明细，通过web机反向到服务部署的机器上

server {
    listen 80;
    listen       443 ssl;
    server_name  yapi.xiaofenglang.com;
    
    ssl on;
    ssl_certificate   cert/server.pem;
    ssl_certificate_key  cert/server.key;
    ssl_session_timeout 5m;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
    ssl_protocols  TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;


    charset utf-8;
    location / {
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_connect_timeout 9000; #nginx跟后端服务器连接超时时间(代理连接超时)
        proxy_send_timeout 9000; #后端服务器数据回传时间(代理发送超时)
        proxy_read_timeout 9000; #连接成功后，后端服务器响应时间(代理接收超时)
        proxy_pass  http://10.2.1.2:3000/;
    }
}

利用pm2方便服务管理维护

npm install pm2 -g  //安装pm2
cd  {项目目录}
pm2 别名启动
pm2 start "vendors/server/app.js" --name yapi //pm2管理yapi服务
pm2 info yapi //查看服务信息
pm2 stop yapi //停止服务
pm2 restart yapi //重启服务

其他碎片说明
yapi 单独重启，如果起不来可以看到错误
node vendors/server/app.js
如果成功停掉用，用pm2启动

pm2 start vendors/server/app.js --watch
pm2 守护进程启用
pm2 list
pm2 stop 0 
pm2 stop all 停止
pm2 restart all 重启


PM2常用命令
https://blog.csdn.net/taoerchun/article/details/81537654
https://blog.csdn.net/u014636209/article/details/100163038

Ypai升级

升级项目版本是非常容易的，并且不会影响已有的项目数据，只会同步 vendors 目录下的源码文件。

cd  {项目目录}
yapi ls //查看版本号列表
yapi update //更新到最新版本
yapi update -v {Version} //更新到指定版本

四、使用说明

建议用谷歌浏览器

需要谷歌浏览器安装yapi扩展程序，安装步骤如下：

1.下载链接 首先手动下载 zip 文件，然后解压。

2.谷歌浏览器中，输入 chrome://extensions 会进入扩展程序

3.右上角打开“开发者模式”

4.然后点击加载已解压的扩展程序，选择第一步的文件。安装完毕。

YApi使用步骤：

1.配置 host 10.2.1.1 yapi.xiaofenglang.com

2.访问地址 http://yapi.xiaofenglang.com 或（如果配置host出现问题，可直接访问地址http://10.2.1.2:3000/）

3.LDAP登录方式 用户名和密码同公司JIRA，用户名是邮箱

4.登录成功后是没有账号权限的。通过组织OA找相关业务线负责人开通权限。

注：业务线中的接口项目分类，由业务线的后端技术leader进行拆分

五、重点功能说明

环境配置

可以配置多环境，例如SIT、UAT、准生产等环境，方便切换。

可配置全局header头，加入token等参数。

全局变量

用户可以在环境列表中定义全局变量的名称和值, 接口运行或者测试集合里面可以通过 {{ global.err }} 来访问当前环境变量下定义的全局变量

数据Mock功能（推荐使用）

Mock功能属于核心功能，可以在后端接口不通的情况下，只要提前定义好参数，前端工程师就可以调试数据了，前后端互不影响。

YApi的 Mock 功能可以根据用户的输入接口信息如协议、URL、接口名、请求头、请求参数、返回数据（[返回数据](#mock)）生成 Mock 接口，这些接口会自动生成模拟数据，创建者可以自由构造需要的数据。

mock地址解析：YApi平台网址 + mock + 您的项目id + 接口实际请求path

具体Mock的使用请参照官网文档说明 https://hellosean1025.github.io/yapi/documents/mock.html

数据导入

YApi 目前支持 postman, swagger, har 数据导入。

请各业务线注意：导入后确定好接口分组和入参是否正确

导入文档说明： https://hellosean1025.github.io/yapi/documents/data.html

六、账号体系说明

暂时无法在文档外展示此内容

七、其他相关资料

互联网中心YApi内网地址 yapi.xiaofenglang.com （用户名和密码同JIRA，如遇到登录问题OA联系相关同学）

游客全局账号（该账号所有人均可访问，只有查看权限，登录时选择普通登录模式） 邮箱：allinapi@mail.com 密码：allinapi

官网资料参考：

git地址： https://github.com/ymfe/yapi

官方教程和文档说明： https://hellosean1025.github.io/yapi/documents/index.html

自动更新Swagger接口数据到YApi平台： https://juejin.cn/post/6844903604692713485

自动化测试实例： https://juejin.cn/post/6844903538011684877

八、常见问题

当接口采用 Mock 时，Mock数据怎么设置？

建议返回数据设置 Mcok 字段尽量固定数据内容而不是直接选择返回数据的类型，因为mock随机生成的数据跟固定返回的数据可能会有出入，不太符合需求数据格式。

是否可以随意创建项目？

建议个人不要随意创建项目，统一按照公司组织架构，按部门按组提前划分好对应的项目及相应的组长