Linux Swagger API文档如何与CI/CD流程集成

畫卷琴夢

发布时间：2025-04-27 08:32:26

376人浏览过

来源于php中文网

原创

将swagger api文档集成到ci/cd流程中，可以确保在代码提交后自动生成api文档，并在每次构建和部署时更新这些文档。以下是一个基本的步骤指南，适用于大多数linux环境下的java或spring boot项目。

1. 选择合适的工具

Swagger/OpenAPI: 用于生成API文档。
SpringDoc: 用于将Swagger 3集成到Spring Boot项目中。
Go-Swagger: 用于在Go语言项目中生成Swagger文档。
FastAPI: 用于快速生成API文档和测试。

2. 生成API文档

使用SpringDoc生成Swagger文档

如果你使用的是Spring Boot项目，可以使用SpringDoc来生成Swagger文档。首先，从pom.xml中移除springfox或swagger的依赖，并添加springdoc-openapi-ui依赖：

<dependency>
    <groupId>org.springdocgroupId>
    <artifactId>springdoc-openapi-uiartifactId>
    <version>1.6.14version>
dependency>

然后，在Spring Boot应用的主类上添加@EnableSwagger2WebMvc注解：

import org.springdoc.core.SwaggerUiOAuthProperties;
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.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Collections.singletonList(apiKey()))
                .securityContexts(Collections.singletonList(securityContext()));
    }

    private ApiKey apiKey() {
        return new ApiKey("JWT", "Authorization", "header");
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any())
                .build();
    }

    private List defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Collections.singletonList(new SecurityReference("JWT", authorizationScopes));
    }
}

使用Go-Swagger生成Swagger文档

如果你使用的是Go语言项目，可以使用go-swagger工具来生成Swagger文档。首先，安装go-swagger工具：

go install github.com/swaggo/swag/cmd/swag@latest

然后在项目根目录下运行以下命令生成文档：

ChatX翻译

最实用、可靠的社交类实时翻译工具。支持全球主流的20+款社交软件的聊天应用，全球200+语言随意切换。让您彻底告别复制粘贴的翻译模式，与世界各地高效连接！

下载

swag init

3. 集成到CI/CD流程

使用Jenkins

安装Jenkins插件: 安装必要的插件，如Docker, Pipeline, Swagger等。
配置Jenkins Pipeline: 创建一个Jenkinsfile，定义CI/CD流程。例如：

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean install'
            }
        }
        stage('Generate Docs') {
            steps {
                sh 'swag init'
            }
        }
        stage('Deploy') {
            steps {
                // 部署到测试环境或生产环境
            }
        }
    }
}

使用Drone

安装Drone: 在Linux服务器上安装Drone CI/CD系统。
配置Drone: 创建.drone.yml文件，定义CI/CD流程。例如：

kind: pipeline
type: docker
name: api-docs

steps:
  - name: build
    image: maven:3.8.3-open
    pull: if-not-exists
    volumes:
      - name: maven_cache
        host: /root/.m2
    commands:
      - mvn clean package
  - name: deploy
    image: appleboy/drone-ssh
    settings:
      host: 172.17.0.1
      username: root
      password: xxxxx
      port: 22
    script:
      - cd /opt/beiming-talk/backend
      - docker build -t my-api-docs .
      - docker push my-api-docs