使用docker搭建yapi接口文档平台

怎样使用yapi搭建自己的接口文档平台
发表于 2023/05/03

一、概述

yapi是一个开源的接口文档平台，可以用于管理接口文档，同时可以进行接口测试。本文将介绍如何使用yapi搭建自己的接口文档平台。其开源地址为：https://github.com/YMFE/yapi。

以下是我本次的运行环境：

环境：云轻量服务器
操作系统： Debian 11
二、准备docker环境
1.1 安装docker
我们将在docker中运行yapi，所以需要安装docker，安装命令如下：

curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

以上命令是使用阿里云的镜像源安装docker，因为在国内，使用阿里云的镜像源会快很多。如果不想使用阿里云的镜像源，直接去掉–mirror Aliyun即可。

1.2 安装docker-compose
docker-compose是docker的一个单机编排工具，用于管理多个容器。这是docker-compose的官网文档链接：https://docs.docker.com/compose/。

本次我们使用独立安装的方式安装dcoker-compose，安装命令如下：

# 下载docker-compose二进制安装文件
curl -SL https://github.com/docker/compose/releases/download/v2.18.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose

赋予docker-compose可执行权限

chmod +x /usr/local/bin/docker-compose

为了检测docker-compose是否安装成功，可以执行如下命令：

docker-compose

如果安装之后执行docker-compose命令没有报错，说明安装成功。否则请检查安装过程是否有问题。你也可以在/usr/bin目录创建软链接。

ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

我们安装好之后，docker-compose命令等同于docker compose命令。其区别在于，docker-compose命令代表它是独立安装的，而docker compose命令是docker的子命令。

三、安装yapi
我们选择服务器的一个空目录，用于存放yapi的配置文件和数据文件。这里我选择的目录是/data/yapi，在下文我把这个目录叫做“工作目录”。

3.1 定义yapi的Dockerfile文件
在工作目录下创建Dockerfile文件，内容如下：

FROM node:12-alpine

RUN npm install -g yapi-cli --registry https://registry.npmmirror.com

EXPOSE 3000 9090

以上文件是用于构建yapi的docker镜像，其中node:12-alpine是yapi的运行环境，yapi-cli是yapi的命令行工具，EXPOSE是yapi的端口。其中9090端口是yapi的安装程序的服务端口，3000端口是yapi的服务端口。

3.2 定义yapi的docker-compose.yml文件
在工作目录下创建docker-compose.yml文件，内容如下：

version: '3.1'

services:
  mongo:
    image: mongo
    restart: always
    volumes: 
        - ./mongo/data/db:/data/db
    ports: 
        - 27017:27017
    container_name: mongo
    healthcheck:
      test: ["CMD", "netstat -anp | grep 27017"]
      interval: 2m
      timeout: 10s
      retries: 3
  yapi:
    build:
      context: ./
      dockerfile: Dockerfile
    image: yapi
    # first run
    command: "yapi server"
    # after first run
    # command: "node /my-yapi/vendors/server/app.js"
    volumes: 
        - ./my-yapi:/my-yapi
    ports: 
      - 9090:9090
      - 3000:3000
    container_name: yapi
    depends_on: 
      - mongo

在以上配置文件中，即使容器被删除，数据也不会丢失，这是因为我们使用了volumes配置项。如下：

1. mongo服务的volumes配置项，是用于持久化mongo的数据
2. yapi服务的volumes配置项，是用于持久化yapi的数据

3.3 启动yapi安装服务
在工作目录下执行如下命令：

docker-compose up -d

这个命令会启动mongo和yapi两个容器，其中mongo容器是用于存储yapi的数据，yapi容器是用于安装yapi的。服务正常启动之后，我们在浏览器中访问http://<服务器IP>:9090，即可看到yapi的安装界面。

进入安装界面之后，我选择最新的版本进行安装，填写配置如下图

填好配置之后，点击开始部署按钮，即可开始安装。安装完成之后，会提示成功安装的管理员信息，我们需要将这些信息保存下来，以便后续登录使用。默认情况下，管理员的账号是我们配置的邮箱，密码是ymfe.org。

如果在安装过程中出现错误，可以通过docker-compose logs命令查看日志。

3.4 启动yapi服务
安装完成之后，我们需要启动yapi服务，我们先销毁现有的容器，如下命令

docker-compose down

修改docker-compose.yml文件，将yapi服务的command配置项修改为如下：

command: "node /my-yapi/vendors/server/app.js"

然后执行如下命令启动yapi服务

docker-compose up -d

四、使用注意事项
4.1 浏览器跨域请求插件
在浏览器中访问http://<服务器IP>:3000，即可看到yapi的登录界面。需要注意的是，如果我们需要在浏览器使用yapi请求接口，我们需要在浏览器中安装yapi的跨域请求插件，地址如下：

• Chrome:
  https://chrome.google.com/webstore/detail/yapi-x/ebiododddhjccikhminneafpoppneknc
• Edge:
  https://microsoftedge.microsoft.com/addons/detail/crossrequest/bephiepmhphdlafkfonngafenjhfehlb

如果你在安装的时候，发现这两个链接失效了，可以直接在浏览器的插件商店中搜索yapi，即可找到对应的插件。或者通过源码的方式进行安装，此处不再赘述。源码地址为: https://github.com/YMFE/cross-request

4.2 开启邮件服务和关闭注册功能
我们可以通过yapi的配置文件，开启邮件服务和关闭注册功能。我们需要在工作目录下的my-yapi目录修改config.json文件，内容如下：

{
   "port": "3000",
   "adminAccount": "phy.xyz@foxmail.com",
   "closeRegister": true,
   "db": {
      "servername": "mongo",
      "DATABASE": "yapi",
      "port": "27017"
   },
   "mail": {
      "enable": true,
      "host": "smtp.qq.com",
      "port": 465,
      "from": "QQ邮箱地址",
      "auth": {
         "user": "QQ邮箱地址",
         "pass": "QQ邮箱密码"
      }
   }
}

其中，closeRegister配置项是用于关闭注册功能，mail配置项是用于邮件服务。

4.3 使用nginx反向代理
推荐使用Nginx反向代理，可以让我们在浏览器中直接访问http://域名，而不是http://<服务器IP>:3000。我们需要创建一个nginx的配置文件，内容如下：

server {
        listen      80;
        server_name yapi.jkdev.cn;

        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
        
        location / {
            proxy_pass http://127.0.0.1:3000/;
        }
}

以上配置文件是用于将http://yapi.jkdev.cn反向代理到服务器的3000端口。我们需要将这个配置文件放到nginx的vhost配置文件目录，一般在/etc/nginx/conf.d目录下，然后执行nginx -s reload命令，即可生效。