还在手写API文档？有那时间撸游戏、耍手机不香咩？

一行Java

发布于 2022-04-06 17:10:04

3860

发布于 2022-04-06 17:10:04

前言

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

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

测试源码

源码：https://gitee.com/pengfeilu/apigcc-demo

导读

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

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

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

自动化部署

图示部署过程

第一步，配置文档生成

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

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

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

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

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

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

第四步，脚本创建

目录 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中下载代码的账户

第六步，添加构建脚本

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脚本的方式进入到各个模块中（具体的模块名称可以根据实际情况调整），并执行打包指令，打包编译出每个模块的文档

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

最后的日志输出打包后的结果

第七步，自动构建测试

添加接口前的文档

添加一个订单修改的接口

/**
 * 修改订单
 * @param orderInfo 修改的订单信息
 * @return 是否修改成功
 */
@PostMapping("update")
public Integer update(@RequestBody OrderInfoRo orderInfo){
    return 1;
}

提交并自动构建

由于太长了，gif缺失了后面的一小段构建成功的部分

构建成功后刷新文档页面

总结

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