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

前语

先来描绘下背景：由于新公司事务归于自研产品开发，可是发现各产品事务线关于接口文档暂时仍是经过集成Swagger来保护，精确来说是knife4j（Swagger的增强解决方案）。可是关于产品型开发而言，会发生一些如项目代码侵入性高、版别兼容问题、文档完全标准化较难、团队无法在线协平等的问题。个人主张Swagger更适合用于一些对接口标准及保护要求较低的职业项目类软件开发，相关于开发而言，接口的文档生成及调试更加方便快捷。

所以这儿结合个人之前的运用经验以及其他接口文档途径调研如下：

结构	Swagger	Yapi	Showdoc	ApiPost
代码侵入性	强	无	无	无
私有化布置	支撑	支撑	支撑	不支撑
是否开源	是	是	是	否
学习成本	较高	简略	简略	较高
主动生成文档	支撑	插件支撑	需求客户端	支撑
数据Mock	支撑	支撑	不支撑（需求客户端）	支撑
主动化测验	不支撑	支撑	需求客户端	支撑
数据导入	不支撑	支撑postman/swagger/har/json	不支撑	支撑postman
补白

当然还有其他很多能够用于接口文档保护的，像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.org
EXPOSE 3000 3000

2.编写docker-compose

这儿运用docker-compose的方法制造镜像以及发动布置，

vi docker-compose.yml

# 内容
version: '3'
services:
  yapi:
    build:
      context: ./
      dockerfile: ./Dockerfile
    image: yapi:1.10.2
    container_name: yapi
    # 第一次发动运用
    command: "yapi server"
    # 之后运用下面的指令
    # command: "node /my-yapi/vendors/server/app.js"
    ports:
      - 3000:3000
      # 第一次发动时映射
      - 9091:9090
    volumes:
      - ./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: ./Dockerfile
    image: yapi:1.10.2
    container_name: yapi
    # 第一次发动运用
    # command: "yapi server"
    # 之后运用下面的指令
    command: "node /my-yapi/vendors/server/app.js"
    ports:
      - 3000:3000
      # 第一次发动时映射
      # - 9091:9090
    volumes:
      - ./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登录运用即可。

一些运用主张：

由管理员或各项目负责人添加不同项目分组，以及添加分组成员；

项目分组下以项目迭代版别来分类新建项目，经过项目命名带着版别号作为区分。

测验集合能够用于开发用例自测包括流程主动化测验，实践关于测验人员需求可能不太满意。

接口文档生成插件

尽管Yapi现已接收接口文档途径，满意开发团队对文档的保护需求了，可是咱们知道大多数运用Swagger的开发可能最重视的点便是经过注解会主动生成接口文档，无需手动编写，提高了工作效率。

由于Yapi途径开放了相关API，所以同样支撑外部生成，由于目前公司开发人员根本运用IDEA作为开发东西，暂时只调研了一些支撑IDEA的插件。

归纳运用及对比几个IDEA插件后，像YapiUpload、EasyYapi、Yapi X等，发现EasyApi插件的装备支撑相对友好、文档生成时代码根本无侵入性、自定义功用强大等，一起满意项目接口文档生成较高的标准化需求；尽管自定义功用运用门槛较高，可是项目一次装备后根本无需改动，更多自定义规则装备及功用的具体运用请参阅官网文档。

运用过程：

翻开File/Settings/Plugins查找EasyYapi，挑选install后重启IDEA;
翻开File/Other Settings/EasyApi,在Yapi下装备server和tokens：

server 即布置的Yapi地址，如：http://192.168.20.24:3000 tokens 即yapi项目中用于恳求项目openapi的私有token，获取方法为项目->设置->token 装备 -> 东西标识

三种生成接口文档并上传到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;
    ...
}

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

运用主张：
经过插件来主动生成的接口文档需求自行查看生成的文档是否正确且标准，不正确或不标准的地方需求手动编辑批改。
一些全局的装备，能够在项目或模块目录下新建.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() +">"

参阅文档： github.com/Ryan-Miao/d…

身未动，心已远。

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

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

前语

Yapi布置-docker

MongoDB布置

Yapi布置

接口文档生成插件

相关文章

Spring循环依赖底层实现原理深度剖析

渲染性能优化全局视角

一文解读分布式存储、文件存储、对象存储、块存储的区别

MATLAB计算变异函数并绘制经验半方差图

作者信息