ubuntu swagger如何进行持续部署

1. 前置准备：安装必要工具与环境配置
在Ubuntu系统上实现Swagger持续部署前，需确保以下工具已正确安装：

Java环境：Swagger依赖Java运行，通过sudo apt install openjdk-11-jdk安装OpenJDK 11（或更高版本）；
构建工具：Maven（sudo apt install maven）或Gradle（sudo apt install gradle），用于项目构建与依赖管理；
Swagger工具：Swagger Codegen CLI（用于生成文档，可通过wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.34/swagger-codegen-cli-3.0.34.jar -O swagger-codegen-cli.jar下载）；
CI/CD工具：选择Jenkins、GitLab CI或GitHub Actions等（以Jenkins为例，需提前安装并配置好Agent）。

2. 项目集成：配置Swagger文档生成
在项目中添加Swagger依赖并配置文档生成规则，以Spring Boot项目为例：

Maven依赖：在pom.xml中添加Springfox Swagger2依赖（适用于Spring Boot 2.x）：

<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>

Swagger配置类：创建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")) // 指定Controller包路径
                .paths(PathSelectors.any())
                .build();
    }
}

API注释：在Controller类中使用Swagger注解（如@ApiOperation、@ApiParam）描述接口，例如：

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class UserController {
    @ApiOperation(value = "获取用户列表", notes = "返回所有用户信息")
    @GetMapping("/users")
    public String getUsers() {
        return "User list";
    }
}

3. CI/CD配置：自动化生成与部署流程
以Jenkins为例，创建Pipeline项目并编写Jenkinsfile，定义持续部署流程：

基础结构：

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                checkout scm // 拉取代码
            }
        }
        stage('Build') {
            steps {
                sh 'mvn clean package' // 构建项目
            }
        }
        stage('Generate Swagger Docs') {
            steps {
                sh 'java -jar /path/to/swagger-codegen-cli.jar generate -i src/main/resources/api.yaml -l html -o target/swagger-docs' // 生成HTML格式文档（也可选JSON/YAML）
            }
        }
        stage('Deploy') {
            steps {
                sh 'scp -r target/swagger-docs/* user@your-server:/var/www/html/swagger/' // 将文档部署到Web服务器
            }
        }
    }
}

关键说明：
- Generate Swagger Docs阶段：使用Swagger Codegen CLI根据api.yaml（或api.json）生成静态文档（支持HTML、JSON、YAML等格式）；
- Deploy阶段：通过scp命令将生成的文档复制到Ubuntu服务器的Web目录（如/var/www/html/swagger/），确保服务器已安装Nginx/Apache并配置好静态资源访问权限。

4. 自动化测试：验证文档与接口一致性
在CI/CD流程中添加测试步骤，确保Swagger文档与实际接口一致：

Spring Boot测试：使用MockMvc模拟请求，验证接口返回值与Swagger文档描述是否匹配，例如：

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@SpringBootTest
@AutoConfigureMockMvc
class ApiTests {
    @Autowired
    private MockMvc mockMvc;

    @Test
    void testGetUsersEndpoint() throws Exception {
        mockMvc.perform(get("/api/users"))
               .andExpect(status().isOk())
               .andExpect(content().string("User list")); // 验证返回值与Swagger注释一致
    }
}

集成到Pipeline：在Jenkinsfile的Test阶段添加测试命令：

stage('Test') {
    steps {
        sh 'mvn test' // 执行单元测试与集成测试
    }
}

5. 持续部署触发：实现自动化更新
通过Git钩子或CI/CD工具的Webhook功能，实现代码推送后自动触发部署流程：

Jenkins Webhook配置：在Jenkins项目设置中启用“GitHub hook trigger for GITScm polling”，并在GitHub仓库的Webhook设置中添加Jenkins服务器URL（如http://your-jenkins-server/github-webhook/）；

GitLab CI示例：若使用GitLab，可在项目根目录创建.gitlab-ci.yml文件，定义类似流程：

stages:
  - build
  - generate_docs
  - deploy

build_job:
  stage: build
  script:
    - mvn clean package

generate_docs:
  stage: generate_docs
  script:
    - java -jar /path/to/swagger-codegen-cli.jar generate -i src/main/resources/api.yaml -l html -o public/swagger-docs

deploy_job:
  stage: deploy
  script:
    - scp -r public/swagger-docs/* user@your-server:/var/www/html/swagger/

通过以上步骤，可实现Ubuntu环境下Swagger文档的持续部署，确保接口文档与代码同步更新，减少手动维护成本。

最新问答

相关标签