如何使用Swagger进行Linux API的持续集成与持续部署

1. 准备Linux环境基础依赖
在Linux系统中，首先需要安装Swagger运行所需的Java环境和构建工具（如Maven/Gradle），这是后续步骤的基础。

安装Java环境：使用OpenJDK 11（或更高版本），执行以下命令：
```
sudo apt update && sudo apt install -y openjdk-11-jdk
```
安装构建工具：以Maven为例，执行：
```
sudo apt install -y maven
```
验证安装：java -version（显示Java版本）、mvn -v（显示Maven版本）。

2. 配置项目Swagger文档生成
根据项目框架（如Spring Boot）添加Swagger依赖，并创建配置类启用文档生成。

添加Swagger依赖：

Maven项目：在pom.xml中添加以下依赖（以SpringFox为例）：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

Gradle项目：在build.gradle中添加：

dependencies {
  implementation 'io.springfox:springfox-swagger2:2.9.2'
  implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

创建Swagger配置类：在Spring Boot项目中创建配置类（如SwaggerConfig.java），启用Swagger并指定扫描范围：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 替换为你的控制器包路径
                .paths(PathSelectors.any())
                .build();
    }
}

若使用SpringDoc（更适配OpenAPI 3.0），可替换为springdoc-openapi-ui依赖，并添加@EnableOpenApi注解。

3. 集成持续集成工具（以Jenkins为例）
通过Jenkins实现代码提交后的自动化构建、文档生成与部署。

安装Jenkins及必要插件：在Linux服务器上安装Jenkins，通过“Manage Jenkins”→“Manage Plugins”安装以下插件：
- Pipeline：用于定义CI/CD流程；
- Maven Integration：支持Maven项目构建；
- Swagger Codegen（可选）：用于生成客户端代码。

配置Jenkins Pipeline：创建新的Pipeline项目，在Jenkinsfile中定义流程（以Spring Boot项目为例）：

pipeline {
    agent any
    tools {
        maven 'maven-3.8.6' // 配置Maven环境（需提前在Jenkins中安装）
        jdk 'jdk11'       // 配置Java环境
    }
    stages {
        stage('Checkout') {
            steps {
                git branch: 'main', url: 'https://github.com/your-repo/your-api-project.git' // 替换为你的代码仓库
            }
        }
        stage('Build') {
            steps {
                sh 'mvn clean package' // 编译项目并打包
            }
            post {
                success {
                    junit '**/target/surefire-reports/*.xml' // 发布测试报告
                }
            }
        }
        stage('Generate Swagger Docs') {
            steps {
                sh 'mvn springfox:swagger2' // 生成Swagger文档（需配置swagger-maven-plugin）
                sh 'cp -r target/classes/static/swagger-ui/* /var/www/html/swagger/' // 将文档复制到Web服务器目录（如Nginx）
            }
        }
        stage('Deploy') {
            steps {
                sh 'scp target/your-api-project.jar user@production-server:/opt/app/' // 部署到生产环境
                sh 'ssh user@production-server "systemctl restart your-api-service"' // 重启服务
            }
        }
    }
}

关键说明：

springfox:swagger2：Maven插件，用于生成Swagger JSON文档；
文档部署：将生成的文档复制到Web服务器（如Nginx）的静态资源目录，便于通过URL访问。

4. 验证Swagger UI访问
部署完成后，通过浏览器访问Swagger UI（如http://your-production-server/swagger-ui.html），确认是否能正常显示API文档。若遇到跨域问题，可在Spring Boot项目中配置CORS：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE");
    }
}

5. 持续部署与监控

自动化部署：在Pipeline的Deploy阶段，通过scp或rsync将构建产物（如JAR文件）复制到目标服务器，使用ssh执行重启命令（如systemctl restart your-api-service）。
监控与反馈：集成Prometheus+Grafana监控API性能，通过Jenkins发送邮件/Slack通知构建结果，确保及时响应问题。

最新问答

相关标签