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

制作 YApi Docker 镜像

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

1
docker pull registry.cn-hangzhou.aliyuncs.com/jboost/yapi
  1. 编写 Dockerfile

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    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"]
  2. 构建镜像

    1
    docker build -t yapi .

部署 YApi 服务

  1. 部署 MongoDB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
#创建 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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    {
    "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"
    }
    }
    }
  2. 初始化及启动 YApi

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    #初始化
    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. 权限

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

其它:

评论