如何使用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通知构建结果，确保及时响应问题。

最新问答

相关标签