ubuntu swagger如何进行持续部署

时间2025-10-25 01:46:04发布访客分类主机资讯浏览286

导读：1. 前置准备：安装必要工具与环境配置在Ubuntu系统上实现Swagger持续部署前，需确保以下工具已正确安装： Java环境：Swagger依赖Java运行，通过sudo apt install openjdk-11-jdk安装Op...

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文档的持续部署，确保接口文档与代码同步更新，减少手动维护成本。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！

若转载请注明出处： ubuntu swagger如何进行持续部署
本文地址： https://pptw.com/jishu/735241.html

ubuntu swagger如何进行版本迭代 ubuntu iptables如何查看状态