使用YApi来统一管理API文档(Docker部署)

一般项目都集成了 Swagger 来提供接口文档，项目一多，前端开发人员就需分别记录各个项目的接口文档地址，不便于统一管理与维护。YApi（开源地址：https://github.com/YMFE/yapi） 提供了一个统一的接口管理服务，基于 YApi，开发者可以轻松创建、发布、维护与调试 API， 同时提供了定时从 Swagger 地址同步接口的功能。本文介绍采用 Docker 部署 YApi 服务，及其基本使用。

制作 YApi Docker 镜像

下列步骤是通过源码自己制作 Docker 镜像，也可以跳过直接获取作者制作的镜像：

docker pull registry.cn-hangzhou.aliyuncs.com/jboost/yapi

1. 编写 Dockerfile

FROM node:12-alpine as builder
WORKDIR /yapi
RUN apk add --no-cache wget python make
ENV VERSION=1.9.2
RUN wget https://github.com/YMFE/yapi/archive/refs/tags/v${VERSION}.zip
RUN unzip v${VERSION}.zip && mv yapi-${VERSION} vendors
RUN cd /yapi/vendors && npm install --production --registry https://registry.npm.taobao.org

FROM node:12-alpine
MAINTAINER ronwxy
ENV TZ="Asia/Shanghai"
WORKDIR /yapi/vendors
COPY --from=builder /yapi/vendors /yapi/vendors
RUN mv /yapi/vendors/config_example.json /yapi/config.json
EXPOSE 3000
ENTRYPOINT ["node"]

1. 构建镜像

docker build -t yapi .

部署 YApi 服务

1. 部署 MongoDB

#创建 MongoDB 数据卷
docker volume create mongo_data 
#拉取镜像
docker pull mongo:latest
#启动，--auth 表示需要密码才能访问
docker run -d --name mongo -p 27017:27017 -v mongo_data:/data/db mongo --auth  
#登入MongoDB
docker exec -it mongo mongo admin
#创建一个用户admin
>  db.createUser({ user:'admin',pwd:'123456',roles:[ { role:'userAdminAnyDatabase', db: 'admin'}]});
#登录
>  db.auth("admin","123456")
#赋予root角色
>  db.grantRolesToUser("admin", [ { role: "root", db: "admin" } ])

1. YApi 配置文件 config.json

{
  "port": "3000",
  "adminAccount": "admin@admin.com",
  "timeout":120000,
  "db": {
    "servername": "192.168.40.10",
    "DATABASE": "yapi",
    "port": 27017,
    "user": "admin",
    "pass": "123456",
    "authSource": "admin"
  },
  "mail": {
    "enable": true,
    "host": "smtp.qq.com",
    "port": 465,
    "from": "xx@qq.com",
    "auth": {
      "user": "xx@qq.com",
      "pass": "xxxxxx"
    }
  }
}

1. 初始化及启动 YApi

#初始化
docker run -it --rm \
--entrypoint npm \
--workdir /yapi/vendors \
-v $PWD/config.json:/yapi/config.json \
yapi run install-server


#启动
docker run -d --name yapi \
--workdir /yapi/vendors \
-p 5000:3000 \
-v $PWD/config.json:/yapi/config.json \
yapi server/app.js

使用 YApi

服务启动后，浏览器访问 http://ip:5000/ 打开 YApi，使用 admin@admin.com
ymfe.org
（默认密码） 登录，登录后可以修改密码。

1. 分组

项目以分组进行归类。只有超级管理员才能创建分组，默认有一个“个人空间”分组。如图，点击图中按钮可创建分组

1. 项目

在分组下创建项目，如图

1. 接口

可以在项目中手动添加接口，也可以通过数据导入的方式导入接口数据，如图通过 Swagger 接口进行导入，

此处 url 填入 Swagger 的 api-docs 地址，形如：http://xxx:8000/context-path/v2/api-docs

也可以在项目设置中开启自动同步，如图

接口导入后，可在接口详情页“运行”中对接口进行调用调试（需要安装 Chrome 插件），类似 Postman，也可以进行 Mock 测试。

1. 权限

可基于分组与项目管理成员权限。

其它：

• 非 Docker 部署方式：https://hellosean1025.github.io/yapi/devops/index.html
• 详细教程：https://hellosean1025.github.io/yapi/documents/index.html