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

  |   0 评论   |   浏览

image-20201115233510014

前言

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

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

测试源码

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

导读

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

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

自动化部署

图示部署过程

image-20201115215836154

第一步,配置文档生成

通过 《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 其中的示例也是基于本文的示例写的。

第四步,脚本创建

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;
    }
    
  • 提交并自动构建
    GIF20201115223639.gif

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

  • 构建成功后刷新文档页面image-20201115230315282

总结

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

更多思考



标题:5分钟集成实现SpringBoot自动生成API接口文档(下篇)
作者:码霸霸
地址:https://blog.lupf.cn/articles/2020/11/15/1605454832274.html