股票程序化交易接口-保姆级文档接口平台Yapi及接口文档生成插件部署使用

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

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

代码侵入性	强	无	无	无
私有化部署	支持	支持	支持	不支持
是否开源	是	是	是	否
学习成本	较高	容易	容易	较高
自动生成文档	支持	插件支持	需要客户端	支持
数据Mock	支持	支持	不支持（需要客户端）	支持
自动化测试	不支持	支持	需要客户端	支持
数据导入	不支持	支持postman/swagger/har/json	不支持	支持postman
备注

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

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

Yapi部署-docker

首先Yapi项目由去哪儿网开源在GitHub，官方文档中有详细的相关介绍，同时也有平台体验地址，这里不再过多赘述。由于公司项目中已经使用docker来构建环境，所以这里主要介绍如何基于docker镜像来制作部署。其实docker部署的方式跟非docker基本相差不多，只是在流程上多了一个镜像制作，市面上也有一些博客文章也已经介绍过了，包括一些已经制作好并push的镜像，但是Yapi最新的10版本的镜像制作部署的文章暂时还没有发现，虽然看上去大同小异，但是实际操作下来还是有一些坑的；同时自己制作的镜像也更加放心安全。

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

nodejs

MongoDB部署

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

下载官方镜像，这里版本选择6

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

启动容器

 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

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

设置用户密码

使用下面命令进入到容器中，并进入到MongoDB的命令行，同时切换到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。

vi Dockerfile

# 内容
FROM node:11
RUN npm install -g yapi-cli --registry https://registry.npm.taobao.org

EXPOSE 3000 3000

这里使用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

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

制作镜像及安装

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

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

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

由于刚才我们将9090映射到9091端口，所以这里访问http://19162240:909能看到网页显示如下，

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

启动

接下来修改docker-composyml如下，


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

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

-d：后台启动

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

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

访问

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

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

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

接口文档生成插件

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

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

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

使用步骤：

打开File/Settings/Plugins搜索EasyYapi，选择install后重启IDEA;打开File/OtherSettings/EasyApi,在Yapi下配置server和tokens：

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

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

/**
 * 分类名称
 * 分类备注/描述
 */
@RestController
@RequestMapping(value = '/demo')
public class DemoController {

    /**
    * api名称
    * api描述
    * @param param1 参数1的名称或描述
    * @param param2 参数2的名称或描述
    * @return
    */
    @GetMapping(value = '/test')
    public Result 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及接口文档生成插件部署使用

股票程序化交易接口-常见的系统间接口方式 01 远程函数调用

股票程序化交易接口-spring钩子方法和钩子接口的使用详解

股票程序化交易 接口-常见的系统间接口方式 01 远程函数调用

股票程序化交易 接口-spring钩子方法和钩子接口的使用详解

股票程序化交易接口-常见的系统间接口方式 01 远程函数调用

股票程序化交易接口-spring钩子方法和钩子接口的使用详解