5分钟集成实现SpringBoot自动生成API接口文档（上篇）

客官°小女子只卖身不卖艺 2022-12-21 10:47 151阅读 0赞

![image-20201115233510014][]

当你问10个开发人员想不想写开发文档，可能有11个人会告诉你，不想写；那有没有方式可以不写接口文档，能自动生成呢？当然是有的，业界比较主流的是使用丝袜哥(swagger)；但是个人使用过程中，觉得它对代码的侵入性有点强，虽然减轻了文档撰写的工作量，但是带来了一些编码的负担，同时和整个业务功能耦合的比较严重；

下面推荐一个**非侵入的API生成工具**：[apigcc][] : https://github.com/apigcc/apigcc 使用起来也非常的简单，而且对代码几乎零侵入。

话不多说，代码走着。。。

#### 测试源码 ####

[源码][Link 1] ：https://gitee.com/pengfeilu/apigcc-demo

#### 入门基础教程 ####

> 开始5分钟的集成示例；

##### 单模块图示 #####

![image-20201115215421046][]

##### 第一步，引入jar #####

<dependency>
        <groupId>com.github.apiggs</groupId>
        <artifactId>apiggs-maven-plugin</artifactId>
        <version>1.6</version>
        <type>pom</type>
    </dependency>

##### 第二步，引入插件 #####

<plugin>
       <groupId>com.github.apiggs</groupId>
       <artifactId>apiggs-maven-plugin</artifactId>
       <version>1.6</version>
       <executions>
          <execution>
             <phase>compile</phase>
             <goals>
                <goal>apiggs</goal>
             </goals>
          </execution>
       </executions>
       <configuration>
          
          <id>index</id>
          <title>订单管理功能API文档</title>
          <production>order</production>
          <out>target/docs</out>
          <dependency>../order/src/main/java</dependency>
          <version>1.0.0</version>
          <description>
             访问：http://127.0.0.1/api/order/[接口名]
    
             非JSON格式传递的参数，请使用form-data的方式传值
    
             默认所有接口请求头部（header）中加入如下参数
                  timestamp: 请求的当前时间戳，秒
                  sign: 进行MD5后的签名
    
          </description>
       </configuration>
    </plugin>

> 值得注意的部分都在configuration里面

*  production
    
    输出的目录名称；一般和项目名称保持一致；默认是apiggs
 *  out
    
    输出的路径；这里设置放置在target/docs目录下
 *  工作路径
    
    源码路径，…/order/src/main/java；主要方便于多个模块配置
 *  version
    
    版本号
 *  description
    
    描述信息，这里可以添加项目特殊的附加信息；比如访问地址，特殊的公共参数；传参方式等等

##### 第三步，测试代码 #####

> 创建一个SpringBoot项目，添加下面的测试代码。

/** * 订单管理 */
    @RestController
    @RequestMapping("/order")
    public class OrderController { 
    
        /** * 根据单号获取的订单 * @param orderNo 订单号 * @return 订单对象 */
        @GetMapping("get")
        public OrderInfoVo getOrder(@RequestParam(defaultValue = "2020111111") String orderNo){ 
            return null;
        }
    
        /** * 创建订单 * @param orderInfo 订单信息 * @return 是否添加成功 */
        @PostMapping("add")
        public Integer add(@RequestBody OrderInfoVo orderInfo){ 
            return 1;
        }
    }

##### 第四步，输出文档 #####

mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs

![image-20201114114347039][]

##### 第五步，页面测试 #####

> 找到输出的目录；双击index.html，即可得到以下api文档界面

![image-20201114114930075][]

##### 第六步，将其配置到web容器中 #####

> 上面得到的只是一个静态的页面，本地访问可以，api文档嘛，毕竟不是给自己看的，主要是给团队的其他同事看的，因此，必定要做到别人能通过浏览器访问到
> 
> 下面就通过Nginx，代理这个静态文件

*  将生成的目录拷贝到nginx所在服务器的任意目录
    
    将文件拷贝到: /opt/apiggs/order
    
    ![image-20201114120038636][]
 *  配置nginx
    
        location /order/
        { 
            root   /opt/apiggs/;
            index  index.html index.htm;
        }
 *  测试
    
    > 访问： http://192.168.1.222/order/index.html
    
    ![image-20201114182035121][]

> 到此，基础的用法已经介绍完了；是不是说5分钟就5分钟，因为真的简单。
> 
> 但是实际开发过程并不会是这么简单的需求，也不可能只是这么一个模块，只会更加的复杂；
> 
> 面对复杂的项目结构，我们该如何处理呢？

#### 实战用法 ####

##### 效果展示 #####

![image-20201114183247994][]

> 如上图所示测试项目；分了好多个模块；订单、商品、用户或者更多；如果生成文档呢？
> 
> 难道每一个模块生成一个？然后放到nginx里面，一个个的访问？
> 
> http://192.168.1.222/order/index.html
> 
> http://192.168.1.222/product/index.html
> 
> http://192.168.1.222/users/index.html 这样？显然不是！！！
> 
> 这样如果涉及到几十个模块，那特么链接就会记疯了，我们希望的是下面这样的效果，用一个**主页页面**把这些模块装起来，然后再分模块展示出来。

![image-20201114183959142][]

##### 开始配置 #####

###### 多模块图示 ######

![image-20201115215550535][]

###### 获取主页页面 ######

> 通过一下链接 获取最新的页面信息
> 
> 这部分内容比较多，就不占篇幅贴出来了

###### 每个模块生成文档 ######

cd ./order
    mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs
                  
    cd ../product
    mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs
                  
    cd ../users
    mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs

![image-20201114185020569][]

###### 将主页页面和模块api页面放到一起 ######

![image-20201114190124394][]

###### 修改主页页面配置 ######

> 第一步下载的那个主页页面index.html

![image-20201114190230057][]

*  第一处，整个项目的名称；页面打开的title
    
        <title>测试项目后台管理接口API</title>
 *  第二处，修改模块信息
    
    > 将下面部分配置，按照自己实际的模块情况修改
    
    ![image-20201114185333295][]

###### 通过nginx代理 ######

*  将文件夹拷贝到nginx服务器
    
    目录：/opt/apiggs/api/
    
    或者直接拷贝到nginx的默认路径： /usr/share/nginx/html/
 *  配置nginx
    
    > **注意**这里只能放置到路径的根目录，如果80端口已经占用；可以配置另外一个端口
    > 
    > 通过端口进行访问
    
        # 用已经在用的端口配置
        location /
        {
            root   /opt/apiggs/api/;
            index  index.html index.htm;
        }
        
        #或者 新开一个server配置
        server {
            listen       8080;
            server_name  localhost;
        
            location /
            {
                root   /opt/apiggs/api/;
                index  index.html index.htm;
            }
        }
    
    重启nginx
    
        nginx -t
        nginx -s reload
 *  测试
    
    > http://192.168.1.222:8080
    
    ![image-20201114192333614][]

#### 自动部署 ####

上面的几轮操作，我们想要的效果已经达到了，但是全程操作都是手动进行；虽然没让我们去写文档；要是每次都按这么一顿操作；那岂不是要把人折磨疯；

下面就带着大家通过 gitlab + jenkins + docker + apigcc 来搭建一个完全解放双手的api生成方案；由于这一块涉及的东西比较多，所以另外起了一个新的博客来介绍；[《5分钟集成实现SpringBoot自动生成API接口文档（下篇）》][5_SpringBoot_API] : https://lupf.cn/articles/2020/11/15/1605454832274.html

![在这里插入图片描述][a62e2e66c9860bdd4bd88f94fe04eead.png_pic_center]

[image-20201115233510014]: /images/20221120/0d64cb0114744f07884da3a939b54871.png
[apigcc]: https://github.com/apigcc/apigcc
[Link 1]: https://gitee.com/pengfeilu/apigcc-demo
[image-20201115215421046]: /images/20221120/1b4746f5de4d48f89cd255107d39e811.png
[image-20201114114347039]: /images/20221120/f28e38cc320546f797f2a36a6a4315a4.png
[image-20201114114930075]: /images/20221120/16e87fd23a5b4f69bf0a17f45fd84e44.png
[image-20201114120038636]: /images/20221120/a23b188cb3284feebf48f6234fe38053.png
[image-20201114182035121]: /images/20221120/2447635addb7490f9d8c95964db79a98.png
[image-20201114183247994]: /images/20221120/090d24361e9b43849ee0ac17ceaacb60.png
[image-20201114183959142]: /images/20221120/6633db218c1c4dfdb0c9678f6945ea6c.png
[image-20201115215550535]: /images/20221120/2a1635b6f01c4d838f5d530c8bff3318.png
[image-20201114185020569]: /images/20221120/1ae00a9b33d1446487d7affc261f6298.png
[image-20201114190124394]: /images/20221120/e96a745ed9884712947c9c18484f08fc.png
[image-20201114190230057]: /images/20221120/429e5432ec69453bb17772fc937c31a7.png
[image-20201114185333295]: /images/20221120/d8e8dbd1498b4126b4bf575b67ec3b79.png
[image-20201114192333614]: /images/20221120/8833b41da6a2461cb84fd4fe42898e6c.png
[5_SpringBoot_API]: https://lupf.cn/articles/2020/11/15/1605454832274.html
[a62e2e66c9860bdd4bd88f94fe04eead.png_pic_center]: https://img-blog.csdnimg.cn/img_convert/a62e2e66c9860bdd4bd88f94fe04eead.png#pic_center