Ubuntu Swagger如何实现持续集成

Ubuntu 下 Swagger OpenAPI 持续集成方案

一 总体流程与工具选型

• 将 **OpenAPI/Swagger 规范文件（YAML/JSON）**纳入 Git 管理，作为唯一事实源。
• 在 Ubuntu 构建机安装基础环境：Docker、Java 11+、Node.js（如需前端或 OpenAPI Generator）。
• 选择文档形态：
  • 静态托管：用 Swagger UI 容器或 openapi-generator 生成 HTML 文档站点。
  • 运行时托管：在 Spring Boot 中集成 springdoc-openapi-ui，随服务启动提供 /swagger-ui.html。
• 在 Jenkins/GitLab CI/GitHub Actions 中编排：拉取代码 → 校验规范 → 生成/构建 → 部署 → 可选通知。

二 快速落地示例

• 示例一 静态站点 + GitLab CI

  • 规范与构建：将 openapi.yaml 置于仓库根目录；使用 openapi-generator 生成静态 HTML 文档并归档。
  • 示例 .gitlab-ci.yml：

    stages:
      - build
      - deploy
    
    variables:
      OPENAPI_GENERATOR_VERSION: "7.10.0"
    
    build-docs:
      stage: build
      image: node:18
      script:
        - npm i -g @openapitools/openapi-generator-cli@$OPENAPI_GENERATOR_VERSION
        - openapi-generator-cli generate -i openapi.yaml -g html -o public/docs
      artifacts:
        paths:
          - public/docs
    
    deploy-pages:
      stage: deploy
      image: alpine
      needs: [build-docs]
      script:
        - mkdir -p /public
        - cp -r public/docs /public
      pages:
        path_prefix: /docs
    

  • 说明：生成的站点可通过 GitLab Pages 访问；也可改为 Nginx 托管或上传至对象存储。

• 示例二 Spring Boot 运行时文档 + Jenkins

  • 依赖（Maven，使用 springdoc-openapi-ui）：

    <
        dependency>
        
      <
        groupId>
        org.springdoc<
        /groupId>
        
      <
        artifactId>
        springdoc-openapi-ui<
        /artifactId>
        
      <
        version>
        1.8.0<
        /version>
        
    <
        /dependency>
    
    

  • 构建与部署（Jenkinsfile 片段）：

    pipeline {
    
      agent any
      stages {
    
        stage('Build') {
    
          steps {
     sh 'mvn -B package -DskipTests' }
    
        }
    
        stage('Test') {
    
          steps {
     sh 'mvn test' }
    
        }
    
        stage('Deploy') {
    
          steps {
    
            sh '''
              docker build -t myapi:$BUILD_NUMBER .
              docker stop myapi || true
              docker rm myapi || true
              docker run -d --name myapi -p 8080:8080 myapi:$BUILD_NUMBER
            '''
          }
    
        }
    
      }
    
    }
        
    

  • 访问：服务启动后打开 http://:8080/swagger-ui.html。

三 规范校验与自动化测试

• 规范校验
  • 使用 openapi-generator-cli validate 在 CI 中对 openapi.yaml 做结构与语义校验，失败即阻断合并。

    openapi-generator-cli validate -i openapi.yaml
    

• 契约/契约测试
  • 使用 Schemathesis 基于 OpenAPI 规范对运行中的服务进行自动化测试（适合在 CI 的部署后阶段执行）。

    pip install schemathesis
    schemathesis run openapi.yaml --base-url http://localhost:8080
    

  • 结合单元测试（如 JUnit/MockMvc 或 pytest）保证接口与文档一致。

四 部署与发布策略

• 静态文档站点
  • 使用 Docker 快速运行 Swagger UI 容器，挂载规范文件或构建产物，便于环境隔离与快速回滚。

    docker run -d -p 38081:8080 \
      -e SWAGGER_JSON=/spec/openapi.yaml \
      -v $PWD/openapi.yaml:/spec/openapi.yaml \
      swaggerapi/swagger-ui:latest
    

  • 适合作为 预览环境 或 GitLab Pages/Nginx 的发布目标。
• 运行时文档
  • 将 springdoc-openapi-ui 随应用一起部署，通过 /swagger-ui.html 访问；在 CI 中配合镜像构建与滚动更新实现零停机发布。
• 版本与变更
  • 将 openapi.yaml 与代码同库管理，利用 CI 阶段门禁（校验/测试）保证每次变更都经过验证；必要时为文档生成 版本化路径/目录。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！