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

偏执的太偏执、 2022-12-21 10:47 132阅读 0赞

![image-20201115233510014][]

#### 前言 ####

这是一篇整合性质的文章，也可以认为是[5分钟集成实现SpringBoot自动生成API接口文档][5_SpringBoot_API](https://lupf.cn/articles/2020/11/14/1605355425671.html)的下篇，是实现真正意义上的自动化，上篇讲的是文档自动生成的过程，如果没看过，请先移步看一下上篇再来阅读此文；虽然能自动生成文档了，但是触发生成的这个动作还是人为控制的，这里就是去掉所有需要人为参与的动作；

写这篇文章的最终目的是将整个**API文档自动生成**周边相关的所有技术点全部都**归纳整理**起来；就算是你没有任何思路，顺着这篇文章，也能把其中涉及到的东西全部学会，并且可以运用到实际的日常开发中去，让你从这些琐碎的事情中抽身出来，做更加有意义的事情。

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

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

#### 导读 ####

开篇有说到，这里是一遍整合性质的文章，所涉及到的周边东西，下面的系列文章中都有详细介绍；你可以根据自己的情况选择性阅读，如果你对该方案相关技术点不了解，可以参考下面的文章做完整的测试。

*  第一篇，**基础文章（重要！！！）**
    
    [《5分钟集成实现SpringBoot自动生成API接口文档（上篇）》][5_SpringBoot_API] ： https://lupf.cn/articles/2020/11/14/1605355425671.html
    
    > 这是一遍基础性文章；本文是对该文章的进一步完善，来真正意义上的做到自动化；所以可以理解为本文是该文的下篇。
 *  第二篇，集成工具**Jenkins**
    
    [《基于Docker 5分钟解决Jenkins环境搭建问题》][Docker 5_Jenkins] : https://lupf.cn/articles/2020/11/07/1604760642788.html
    
    > 持续集成工具；
    > 
    > 本文主要介绍如何通过Docker安装Jenkins；如果你会或者已经正在使用，可以忽略此文
 *  第三篇，**GitLab**私有仓库
    
    [《基于Docker 5分钟搭建GitLab代码仓库》][Docker 5_GitLab] : https://lupf.cn/articles/2020/11/07/1604761653881.html
    
    > 代码托管仓库；
    > 
    > 本文主要介绍如何通过Docker安装GitLab；如果你会或者已经正在使用，可以忽略此文
 *  第四篇
    
    [《Jenkins监听gitlab的提交并自动打包（详细图解）》][5_SpringBoot_API] : https://lupf.cn/articles/2020/11/14/1605355425671.html
    
    > 本文主要介绍如何通过GitLab配置webhook，实现代码提交之后，自动触发Jenkins构建任务。
 *  第五篇；**Linux虚拟机**
    
    [《基于VirtualBox搭建Linux(CentOS 7)虚拟机环境（学习必备技能）》][VirtualBox_Linux_CentOS 7] : https://lupf.cn/articles/2020/04/04/1586001434581.html
    
    > 作用如题。如果你想进行一些测试，可以使用该方式搭建测试环境。
 *  第六篇，**Docker**
    
    [《CentOS 7下安装Docker及基础操作》][CentOS 7_Docker] : https://lupf.cn/articles/2019/11/23/1574503815568.html
    
    > 本文会使用到Docker去部署api服务，所以，不了解Docker的，可以参考此文安装Docker，并了解基础的操作。

上面是相关文章的一个导读，从这里开始；正式开始讲解，如果通过**GitLab + Jenkins + Docker + Apigcc**实现文档自动化生成

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

##### 图示部署过程 #####

![image-20201115215836154][]

##### 第一步，配置文档生成 #####

通过 [《5分钟集成实现SpringBoot自动生成API接口文档（上篇）》][5_SpringBoot_API] ： https://lupf.cn/articles/2020/11/14/1605355425671.html 我们已经学会通过apigcc，生成了模块对应的文档，并且通过一个主页将他们整合起来了；但是这一些的生成和发布动作都存在一部分人为干预的过程，并没有完全实现自动化。下面通过几款集成工具加上相关配置，来完成去掉手动操作的部分。

##### 第二步，将代码推送到GitLab仓库 #####

如果不知道如何搭建和推送，可以参考[《基于Docker 5分钟搭建GitLab代码仓库》][Docker 5_GitLab] : https://lupf.cn/articles/2020/11/07/1604761653881.html 其中的示例也就是使用的本文的示例代码进行测试的。

##### 第三步，Jenkins创建项目并绑定GitLab项目 #####

jenkins创建一个构建项目，并将其与GitLab上的项目绑定，实现GitLab上代码的提交自动触发Jenkins的构建任务；详细可参考

[《Jenkins监听gitlab的提交并自动打包（详细图解）》][5_SpringBoot_API] : https://lupf.cn/articles/2020/11/14/1605355425671.html 其中的示例也是基于本文的示例写的。

##### 第四步，脚本创建 #####

![image-20201114231852411][]

*  目录 api-doc-docker
    
    后续一些脚本都是使用的这个目录名称
 *  Dockerfile
    
    > 构建用于发布api静态文件的镜像
    > 
    > 构建说明：
    > 
    > 基于nginx；会将主页的index.html文件以及创建好的静态API文件放置到容器Nginx默认目录：/usr/share/nginx/html
    
        COPY ./index.html /usr/share/nginx/html/
        
        ADD ./order /usr/share/nginx/html/order
        ADD ./product /usr/share/nginx/html/product
        ADD ./users /usr/share/nginx/html/users
    
    > 注意，这里的文件夹名称，如./order ./product ./users需要根据自己实际的情况来调整
 *  stop\_and\_remove\_old\_version.sh
    
    > 用于停旧版本容器
    > 
    > 删除旧版本的镜像
    
        # 停止并删除容器
        api_doc_run_code=`docker ps -a | grep api-doc |awk '{print $3}' |head -n 1`
        if [ "$api_doc_run_code" != "null" ];
        then
          docker rm -f api-doc
          echo "停止并移除容器:"$api_doc_run_code
        fi
        
        image_version=`docker images | grep api-doc |awk '{print $3}' |head -n 1`
        
        if [ "$image_version" != "null" ];
        then
          docker rmi $image_version
          echo "移除旧版镜像:"$image_version
        fi
    
    > 查找当前运行的容器中名称包含了api-doc对应的容器id
    > 
    > docker ps -a | grep api-doc |awk ‘\{print $3\}’ |head -n 1
    > 
    > 查找镜像中名称包含了api-doc对应的镜像id
    > 
    > docker images | grep api-doc |awk ‘\{print $3\}’ |head -n 1
 *  index.html
    
    > 上篇中涉及到的主页的那个html

##### 第五步，Jenkins中创建GitLab的全局认证用户 #####

通俗点说，就是在jenkins中创建一个用于在gitlab中下载代码的账户

![image-20201114235820588][]

##### 第六步，添加构建脚本 #####

![image-20201115000104441][]

pipeline { 
    
        agent any
        stages { 
            
            stage('下载源码'){ 
                options {  timeout(time: 60, unit: 'SECONDS') }
                steps { 
                    git branch: "master",
                    credentialsId: 'gitlab_root_user',
                    url: 'http://192.168.1.222:880/root/apigcc-demo'
                }
            }
            stage('编译DOC'){ 
                steps { 
                    sh ''' 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 '''
                }
            }
            stage('docker打包'){ 
                steps { 
                    sh ''' echo "${BRANCH_NAME}" cp -r ./order/target/docs/order ./api-doc-docker cp -r ./product/target/docs/product ./api-doc-docker cp -r ./users/target/docs/users ./api-doc-docker ls -l ./api-doc-docker sh ./api-doc-docker/stop_and_remove_old_version.sh docker build ./api-doc-docker/ -t apigcc-api-doc:master '''
                 }
            }
            stage('重启容器'){ 
                steps { 
                    sh ''' docker run -d --restart=unless-stopped -p 7777:80 --name=api-doc apigcc-api-doc:master '''
                 }
            }
            
        }
        post { 
            success { 
                sh ''' git_author_name=$(git show -s --pretty="%an<%ae>") git_push_time=$(git show -s --pretty=%ad) echo "${JOB_NAME} has builded at $git_push_time by $git_author_name " '''
            }
            aborted { 
                sh ''' git_author_name=$(git show -s --pretty="%an<%ae>") git_push_time=$(git show -s --pretty=%ad) echo "${JOB_NAME} has builded timeout at $git_push_time by $git_author_name " '''
            }
        }
    }

*  下载源码
    
    git branch 指明分支名称
    
    credentialsId 上面创建的全局用户对应的那个id
    
    url 项目在GitLab仓库中的地址
 *  编译DOC
    
        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
    
    > 以shell脚本的方式进入到各个模块中（具体的模块名称可以根据实际情况调整），并执行打包指令，打包编译出每个模块的文档
 *  docker打包
    
     *  统一文件目录
        
            cp -r ./order/target/docs/order ./api-doc-docker
            cp -r ./product/target/docs/product ./api-doc-docker
            cp -r ./users/target/docs/users ./api-doc-docker
            ls -l ./api-doc-docker
        
        > 为了方便后续构建镜像，将各个模块打包出来的api静态文件，统一拷贝的api-doc-docker
     *  停止移除老的容器和镜像，创建新的镜像
        
            # 通过脚本停止、删除旧的容器以及其对应的镜像
            sh ./api-doc-docker/stop_and_remove_old_version.sh
            # 基于生成的最新api静态文件，构建一个新的docker镜像
            docker build ./api-doc-docker/ -t apigcc-api-doc:master
 *  重启容器
    
        docker run -d --restart=unless-stopped -p 7777:80 --name=api-doc  apigcc-api-doc:master
 *  最后的日志
    
    > 输出打包后的结果

##### 第七步，自动构建测试 #####

*  添加接口前的文档
    
    ![image-20201115220945940][]
 *  添加一个订单修改的接口
    
        /** * 修改订单 * @param orderInfo 修改的订单信息 * @return 是否修改成功 */
        @PostMapping("update")
        public Integer update(@RequestBody OrderInfoRo orderInfo){ 
            return 1;
        }
 *  提交并自动构建
    
    ![GIF2020-11-1522-36-39][]
    
    > 由于太长了，gif缺失了后面的一小段构建成功的部分
 *  构建成功后刷新文档页面
    
    ![image-20201115230315282][]

#### 总结 ####

到此，一个完全自动化构建部署的API文档生成方案就介绍完了，虽然这个过程稍微复杂一点点，但是结合在实际的使用过程中，发现这种方式更加的灵活、便捷；除了首次部署构建的过程会带来一点小小的负担，但是部署完成之后，对代码的侵入性几乎为0，**代码写完之日就是咱出文档之时**。

#### 更多思考 ####

*  多项目的问题
    
    上面的演示使用的是多模块的方式，日常开发中有多项目的情况，针对多项目，也只是多模块的一个变种；那么就得根据个人实际的情况去调整调节各个模块的发布情况；也只需要基于上面做一些调整
 *  jenkins和部署的不在同一机器上
    
    可能需要将文档发布到jenkins外的其他机器；那就需要将Docker镜像推送到私有或者其他托管的镜像仓库；然后通过jenkins在其他机器上更新下载镜像；并启动容器；这里有一篇基于[《阿里云托管Docker镜像仓库》][Docker] ：https://lupf.cn/articles/2020/11/12/1605160545846.html 的教程；也可以使用harbor搭建私有镜像仓库，[《基于Docker安装Harbor搭建Docker私有仓库》][Docker_Harbor_Docker] :https://blog.csdn.net/lupengfei1009/article/details/105247304

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

[image-20201115233510014]: /images/20221120/3a993afca2f04369b448fa62952d9e9b.png
[5_SpringBoot_API]: https://lupf.cn/articles/2020/11/14/1605355425671.html
[Link 1]: https://gitee.com/pengfeilu/apigcc-demo
[Docker 5_Jenkins]: https://lupf.cn/articles/2020/11/07/1604760642788.html
[Docker 5_GitLab]: https://lupf.cn/articles/2020/11/07/1604761653881.html
[VirtualBox_Linux_CentOS 7]: https://lupf.cn/articles/2020/04/04/1586001434581.html
[CentOS 7_Docker]: https://lupf.cn/articles/2019/11/23/1574503815568.html
[image-20201115215836154]: /images/20221120/29a44f0d1ee44d25acae24a8e6cb0527.png
[image-20201114231852411]: /images/20221120/243fe9c0ce5544a6b4ff9ddd1a9905a9.png
[image-20201114235820588]: /images/20221120/6471f778c598407daa6263bfb5f71701.png
[image-20201115000104441]: /images/20221120/b3621399d07242b8b3248ba5fef50959.png
[image-20201115220945940]: /images/20221120/2273c56ed5d5480c9a8534af30c6f526.png
[GIF2020-11-1522-36-39]: /images/20221120/b48a7a928fd543b5be2a2d713a800c97.png
[image-20201115230315282]: https://img-blog.csdnimg.cn/img_convert/2826246addae66b4959f7e85aa294eae.png
[Docker]: https://lupf.cn/articles/2020/11/12/1605160545846.html
[Docker_Harbor_Docker]: https://blog.csdn.net/lupengfei1009/article/details/105247304
[a62e2e66c9860bdd4bd88f94fe04eead.png_pic_center]: https://img-blog.csdnimg.cn/img_convert/a62e2e66c9860bdd4bd88f94fe04eead.png#pic_center