「安装」推荐一个接口文档管理工具 YApi

在文章开始之前，还是简单摘录官方对 YApi 的介绍，给用过和没用的读者简单说明一下 YApi 是什么。

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

根据官方文档，YApi 主要又两种方式安装，一是使用 yapi-cli 工具可视化安装，另一种是源码安装。其他的安装方式都是在这个基础上进行变化而来，后面就简单介绍一下怎么安装。

环境要求

nodejs（7.6+)
mongodb（2.6+）

可视化部署

注意：确保你的 MongoDB 数据库服务正常启动，并且能够访问。

第一步： 安装 yapi-cli 工具

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

第二步： 使用 yapi 命令可视化部署

yapi server

第三步： 配置 YApi

如果是在本地电脑上运行的，可以使用浏览器打开 127.0.0.1:9090 可视化部署页面。其他的根据实际情况调整 IP。

在对应的配置项填写配置信息，完成后点击 开始部署，等待部署完成。

第四步： 运行 YApi

部署完成之后，按照提示信息，在命令行执行 node /{网站路径/server/app.js} 启动服务器。

在浏览器中打开中打开 127.0.0.1:3000，即可进入 YApi，IP 地址请根据实际情况修改，端口号是之前配置中指定的，默认是 3000。

点击登录，输入之前配置中的管理员邮箱和默认密码(ymfe.org) 登录系统，就可以使用 YApi 进行接口管理了。

强烈建议：前往个人中心修改默认密码。

源代码部署

有时候，我们不想安装工具，只想直接安装，或者部署到一些特殊的服务器，可以考虑使用源代码的方式部署。Windows 平台自行注意命令含义和路径等。

注意：确保你的 MongoDB 数据库服务正常启动，并且能够访问。

第一步： 创建 YApi 存放目录，名称可以自定

mkdir yapi && cd yapi

第二步： 下载源代码，并将文件夹名称重命名为 vendors

使用 Git 命令克隆仓库

git clone --depth=1 https://github.com/YMFE/yapi.git vendors

或者也可以到 https://github.com/YMFE/yapi/tags 下载对应版本的 zip 包，解压到 vendors 目录。

第三步： 创建配置文件

从 vendors 文件夹下复制官方的示例配置文件进行修改

cp vendors/config_example.json ./config.json

第四步： 初始化数据库和管理员账号，数据库链接信息和管理员账号在 config.json 中配置

cd vendors
npm install --production --registry https://registry.npmmirror.com
npm run install-server

在命令行中会输出管理员账号和密码（账号是 config.json 中配置，密码默认是 ymfe.org），表示安装已经完成。

第五步： 启动 YApi 服务器

node server/app.js

第六步： 访问 YApi

使用浏览器 打开 127.0.0.1:{config.json配置的端口}，点击登录，输入第四步中提示输出的管理员账号和密码登录系统。

通过 Docker 安装部署

同一开始介绍的，在 Docker 安装使用是根据前面两种方式修改而来，这里就演示源码版本的安装。

在开始之前，我们需要建立一个 MongoDB 环境。

运行 MongoDB

第一步： 创建存储卷

docker volume create yapi-data

第二步： 启动 MongoDB

docker run -d /
	-v yapi-data:/data/db /
	-e MONGO_INITDB_ROOT_USERNAME=root /
	-e MONGO_INITDB_ROOT_PASSWORD=root /
	--name mongo-yapi /
	--restart always /
	mongo:latest

参数说明：

• -d 表示后台运行容器
• -v yapi-data:/data/db 指定存储卷位置与映射到容器中的位置
• -e MONGO_INITDB_ROOT_USERNAME=root 设置 MongoDB root 用户名为 root
• -e MONGO_INITDB_ROOT_PASSWORD=root 设置 MongoDB root 用户的密码为 root
• –name mongo-yapi 指定运行容器的名称
• –restart always 设置容器的重启规则为 总是
• mongo:latest 镜像的名称和标签

构建 YApi 镜像

第一步： 创建 Dockerfile 文件

可以参考下面的内容，也可以根据自己需求自定义。

FROM node:14-alpine3.16 AS builder
WORKDIR /yapi
RUN apk add --no-cache wget
# 可以指定自己想要的版本号，这里指定的是 1.10.2
ENV VERSION=1.10.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 /
    && cp config_example.json ../config.json /
    && rm -f package-lock.json /
    && npm install --production --registry https://registry.npmmirror.com

FROM node:14-alpine3.16
MAINTAINER [email protected]
ENV TZ="Asia/Shanghai"
WORKDIR /yapi/vendors
COPY --from=builder /yapi/vendors /yapi/vendors
EXPOSE 3000
ENTRYPOINT ["node"]

Windows 注意保存的格式为 无 BOM 头的 UTF-8 文件。

第二步： 运行 Docker 命令构建镜像

docker build -t yapi:1.10.2 .

这里通过 -t 参数指定了镜像的名称和标签，这个由你自己的心情设置，不过后面会用到，所以设置好之后要记得。

运行 YApi 镜像

第一步： 创建 config.json 配置文件

{
  "port": "3000",
  "adminAccount": "[email protected]",
  "timeout":120000,
  "db": {
    "servername": "mongo",
    "DATABASE": "yapi",
    "port": 27017,
    "user": "root",
    "pass": "root",
    "authSource": "admin"
  },
  "mail": {
    "enable": true,
    "host": "smtp.163.com",
    "port": 465,
    "from": "***@163.com",
    "auth": {
      "user": "***@163.com",
      "pass": "*****"
    }
  }
}

上面的内容请根据自己的喜好配置，注意 db 字段下的配置要能确保能够与 MongoDB 数据库连接成功。

创建完成后记一下文件的路径，后面会使用到。

第二步： 初始化数据库和管理员账号

我们通过运行一次镜像的方式用配置文件的信息连接数据库，并将一些信息（如管理员账号等）信息写入数据库，完成初始化。

docker run -it /
	-v $PWD/config.json:/yapi/config.json /
	--rm /
	--link mongo-yapi:mongo /
	--entrypoint npm /
	--workdir /yapi/vendors /
	yapi:1.10.2 /
	run install-server

参数说明：

• -it 表示以交互式命令行启动容器
• -v $PWD/config.json:/yapi/config.json 挂在当前目录下的config.json 文件到容器中的 yapi 目录下。这里也可以根据你自己的 config.json 文件位置进行调整。Windows 环境下注意路径问题。
• –rm 表示容器停止后，容器会被删除。
• –link mongo-yapi:mongo 这是连接之前创建的 MongoDB 容器到 YApi 容器中，并设置为 mongo，便于访问。
• –entrypoint npm 覆盖镜像中的默认入口点为 npm，为后面的运行初始化命令提供方便。
• –workdir /yapi/vendors 设置容器运行时的工作目录。
• yapi:1.10.2 我们之前构建的镜像名称和标签，这里需要根据你的实际情况进行修改。
• run install-server 是要在容器用运行的命令，这里与 entrypoint 参数配合之后的完整命令是 npm run install-server

第三步： 启动 Yapi 服务

docker run -d /
	-p 3000:3000 /
	-v $PWD/config.json:/yapi/config.json /
	--link mongo-yapi:mongo /
	--name yapi /
	--restart always /
	--workdir /yapi/vendors /
	yapi:1.10.2 /
	server/app.js

参数说明：

• -d 表示后台运行容器
• -p 3000:3000 指定容器暴露的端口号，以便在容器外也能进行访问。
• -v $PWD/config.json:/yapi/config.json （和前面一样）挂在当前目录下的config.json 文件到容器中的 yapi 目录下。
• –link mongo-yapi:mongo （和前面一样）连接之前创建的 MongoDB 容器到 YApi 容器中。
• –name yapi 指定运行后的容器的名称，可以不设置，会自动生成一个随机的名称，也可以在根据自己喜好设置。
• –restart always 设置容器的重启规则为 总是
• –workdir /yapi/vendors 设置容器运行时的工作目录。
• yapi:1.10.2 我们之前构建的镜像名称和标签，这里需要根据你的实际情况进行修改。
• server/app.js 运行的脚本名称。因为这里没有设置 entrypoint 参数，所以会使用构建好的镜像中设置的 ENTRYPOINT，完整的命令是 node server/app.js

其他

到了这里之后，一般都可以完成 YApi 的 Docker 方式部署，后面就是在浏览器中打开链接验证和使用了，具体步骤在前面已经说明了，这里就不再重复累赘了。

如果还有其他什么问题，也可以留言给我，我看到了会尽我所能解决你遇到的问题。

另外，因为我个人能力问题，文中有说得不恰当的地方，也欢迎大家指正。

谢谢看到这里的每一个人，愿我所闻，解你之惑，是我之幸，点点萤火，可以燎原。