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

0 赞

0 踩