保姆级文档-接口平台Yapi及接口文档生成插件部署使用

前言

先来描述下背景：由于新公司业务属于自研产品开发，但是发现各产品业务线对于接口文档暂时还是通过集成Swagger来维护，准确来说是knife4j（Swagger的增强解决方案）。但是对于产品型开发而言，会产生一些如项目代码侵入性高、版本兼容问题、文档完全规范化较难、团队无法在线协同等的问题。个人建议Swagger更适合用于一些对接口规范及维护要求较低的行业项目类软件开发，相对于开发而言，接口的文档生成及调试更加方便快捷。

所以这里结合个人之前的使用经验以及其他接口文档平台调研如下：

当然还有其他很多可以用于接口文档维护的，像postman、RAP、EasyAPI等平台，文档型的像云雀、石墨文档、wiki等，各有优点以及适用的业务场景。

最后决定使用支持私有部署及swagger同步导入的开源平台 Yapi 来保存和维护各项目中的接口文档；当然不可避免，作为无偿的开源产品，它也会有一些瑕疵，比如目前开源维护度低（导致社区活跃度也相对减少很多）、平台中目录层级不支持二级以上（需要二次开发，一些fork版本虽然支持，但是版本较低）、一些版本存在的bug（参考issue）等。

但是这些都影响不大，最重要的还是考虑公司业务及技术团队的当前实际需求及后续扩展基本能很好的满足。

Yapi部署-docker

首先Yapi项目由去哪儿网开源在GitHub，官方文档中有详细的相关介绍，同时也有平台体验地址，这里不再过多赘述。

由于公司项目中已经使用docker来构建环境，所以这里主要介绍如何基于docker镜像来制作部署（非docker环境推荐官方提供的yapi-cli工具部署文档，简单易用，且无缝支持版本升级；而非一些博客文章，由于文章描述及水平参差不齐，可能会反向误导）。

其实docker部署的方式跟非docker基本相差不多，只是在流程上多了一个镜像制作，市面上也有一些博客文章也已经介绍过了，包括一些已经制作好并push的镜像，但是Yapi最新的1.10版本的镜像制作部署的文章暂时还没有发现，虽然看上去大同小异，但是实际操作下来还是有一些坑的；同时自己制作的镜像也更加放心安全。

首先我们了解到Yapi的环境要求：

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

MongoDB部署

因为接口的数据使用NoSQL数据库mongodb进行存储，所以我们首先需要安装部署mongodb。

1.下载官方镜像，这里版本选择4.2.6

docker pull mongodb:4.2.6

执行命令docker images可以看到镜像已经下载完成

2.启动容器

 docker run  \
--name mongo \
-p 27017:27017  \
-v /data/yapi/mongodb/data/configdb:/data/configdb/ \
-v /data/yapi/mongodb/data/db/:/data/db/ \
-d mongo:4.2.6 --auth

• -p 27017:27017：映射容器的访问端口。
• -v 参数：将MongoDB容器中的数据挂载到外部目录，这样不可预料的意外导致容器无法恢复启动，也能保护原来的数据。
• –auth：需要密码才能访问MongoDB。

使用命令docker ps可以看到容器已经正常启动

3.设置用户密码

使用下面命令进入到容器中，并进入到MongoDB的命令行，同时切换到admin数据库

docker exec -it mongo mongo admin

设置一个用户和密码，然后验证是否正确

db.createUser({ user:'admin',pwd:'123456',roles:[ { role:'userAdminAnyDatabase', db: 'admin'}"readWriteAnyDatabase"]});# 验证
db.auth('admin', '123456')

到这里MongoDB就部署完成了，后续注意对MongoDB的数据文件定时备份就行了（相关文章很多，这里不赘述了）。

Yapi部署

部署Yapi前，我们需要自己制作docker镜像，这里有两种方式

• 源码编译
• 官方yapi-cli工具

其中源码编译的方式稍微复杂点，对不同版本的环境依赖可能会产生一些坑，而且版本升级也相对麻烦点；这里推荐第二种方式，也就是yapi-cli。

1.编写Dockerfile

vi Dockerfile# 内容
FROM node:11
RUN npm install -g yapi-cli --registry https://registry.npm.taobao.orgEXPOSE 3000 3000

2.编写docker-compose

这里使用docker-compose的方式制作镜像以及启动部署，

vi docker-compose.yml# 内容
version: '3'services:yapi:build:context: ./dockerfile: ./Dockerfileimage: yapi:1.10.2container_name: yapi# 第一次启动使用command: "yapi server"# 之后使用下面的命令# command: "node /my-yapi/vendors/server/app.js"ports:- 3000:3000# 第一次启动时映射- 9091:9090volumes:- ./my-yapi:/my-yapi

• dockerfile：执行当前目录下的Dockerfile来制作镜像。
• image：命名镜像的名称及tag。
• volumes：将容器中yapi的文件挂载到外部目录，包括配置文件。

这里注意，第一次启动的时候需要执行yapi-cli命令来帮助安装，所以需要使用command: "yapi server"及- 9091:9090，安装完成后重新执行docker-compose前把其注释即可。

3.制作镜像及安装

编写好所需要的文件之后，执行下面命令，

docker-compose up

首先会下载制作yapi镜像的基础镜像node:11

下载完成后就能看到如下控制台，说明yapi-cli启动完成了

由于刚才我们将9090映射到9091端口，所以这里访问http://192.168.24.240:9091（192.168.24.240为宿主机的ip），能看到网页显示如下，

接下来我们直接在上面设置好然后点击开始部署就可以安装我们想要的版本的yapi了，之后能看到页面以及控制台会不停刷安装的相关log，直到看到下面的信息这说明Yapi已经下载安装好了。

4.启动

到这里就剩最后一步，下面我们直接退出控制台停止运行，由于之前- ./my-yapi:/my-yapi已经将Yapi文件挂载出来了，用ls命令能查看到当前目录下的my-yapi文件，

进入目录后能看到config.json文件，它是Yapi的基础配置文件，可以设置管理员账号、MongoDB连接配置、邮箱通知等等，具体参考官方文档。

接下来修改docker-compose.yml如下，

version: '3'services:yapi:build:context: ./dockerfile: ./Dockerfileimage: yapi:1.10.2container_name: yapi# 第一次启动使用# command: "yapi server"# 之后使用下面的命令command: "node /my-yapi/vendors/server/app.js"ports:- 3000:3000# 第一次启动时映射# - 9091:9090volumes:- ./my-yapi:/my-yapi

修改完成后保存退出，使用下面命令就可以直接启动了，

docker-compose up -d

• -d：后台启动

启动完成后，使用docker ps，能看到我们的Yapi容器已经启动完成了,

同时使用命令docker images也能看到我们制作好的1.10.2的镜像文件，

5.访问

启动完成后我们浏览器直接访问http://192.168.24.240:3000就能看到如下，

接下来我们就用之前配置的管理员账户以及默认密码ymfe.org登录使用即可。

一些使用建议：

1. 由管理员或各项目负责人添加不同项目分组，以及添加分组成员；
2. 项目分组下以项目迭代版本来分类新建项目，通过项目命名携带版本号作为区分。
3. 测试集合可以用于开发用例自测包括流程自动化测试，实际对于测试人员需求可能不太满足。

接口文档生成插件

虽然Yapi已经接管接口文档平台，满足开发团队对文档的维护需求了，但是我们知道大多数使用Swagger的开发可能最关注的点就是通过注解会自动生成接口文档，无需手动编写，提高了工作效率。

因为Yapi平台开放了相关API，所以同样支持外部生成，由于目前公司开发人员基本使用IDEA作为开发工具，暂时只调研了一些支持IDEA的插件。

综合使用及对比几个IDEA插件后，像YapiUpload、EasyYapi、Yapi X等，发现EasyApi插件的配置支持相对友好、文档生成时代码基本无侵入性、自定义功能强大等，同时满足项目接口文档生成较高的规范化需求；虽然自定义功能使用门槛较高，但是项目一次配置后基本无需改动，更多自定义规则配置及功能的详细使用请参考官网文档。

使用步骤：

1. 打开File/Settings/Plugins搜索EasyYapi，选择install后重启IDEA;

   

2. 打开File/Other Settings/EasyApi,在Yapi下配置server和tokens：

server 即部署的Yapi地址，如：http://192.168.20.24:3000
tokens 即yapi项目中用于请求项目openapi的私有token，获取方式为项目->设置->token 配置 -> 工具标识

3. 三种生成接口文档并上传到Yapi的方式（初次使用可能会以弹窗的方式要求输入token）：
   • 打开项目中的包含api的文件或者在IDEA的左边项目文件区域选择文件或者文件夹 鼠标右键点击文件内容或文件夹, 选择ExportYapi 导出该文件或文件夹中所有的api;
   • 打开项目中的包含api的文件或者在IDEA的左边项目文件区域选择文件或者文件夹 使用快捷键alt shift E(windows)/ctrl E(mac) 然后选择要导出的API,选择导出渠道Yapi 点击[✔]按钮或者按回车键完成导出
   • 鼠标点击最上方Code > YapiDashBoard 然后就可以用鼠标将左边的API拖动到右边yapi目录中，完成API导出到Yapi

注意要生成相对规范的接口文档，需要编写较为完整的代码注释，如下(简单的注释Demo)：

/*** 分类名称* 分类备注/描述*/
@RestController
@RequestMapping(value = "/demo")
public class DemoController {/*** api名称* api描述* @param param1 参数1的名称或描述* @param param2 参数2的名称或描述* @return*/@GetMapping(value = "/test")public Result<Demo> methodName1(@RequestParam String param1,@RequestParam(required = false, defaultValue = "1") Integer param2){...}}public class Demo {/*** 字段注释*/private Long field1;/*** 如果使用javax.validation的话* 可以使用@NotBlank/@NotNull表示字段必须*/private String field2;...
}

通过插件上传后，即可在平台目录中看到所生成的接口文档。

使用建议：

1. 通过插件来自动生成的接口文档需要自行查看生成的文档是否正确且规范，不正确或不规范的地方需要手动编辑修正。

2. 一些全局的配置，可以在项目或模块目录下新建.yapi.config来进行配置(更对配置参考官方文档)

   # 参数忽视特定类
   param.ignore=@java.lang.String
   # 参数描述后缀
   param.doc=groovy:",类型<"+tool.uncapitalize(it.type().name().replace("java.lang.","").replace("Long","String")) +">"
   # Long转String
   json.rule.convert[java.lang.Long]=java.lang.String
   # 统一返回体
   method.return[#return]=groovy: "com.xxx.xxx.Result<" + it.returnType() +">"
   

参考文档：
https://github.com/Ryan-Miao/docker-yapi

身未动，心已远。

把一件事做到极致就是天分！