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 阶段门禁（校验/测试）保证每次变更都经过验证；必要时为文档生成 版本化路径/目录。