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

将Swagger API文档集成到CI/CD流程中可以确保在代码提交后自动生成API文档，并在每次构建和部署时更新这些文档。以下是一个基本的步骤指南，适用于大多数Linux环境下的Java或Spring Boot项目。

选择合适的工具

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

生成API文档

使用SpringDoc生成Swagger文档

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

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</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<SecurityReference> 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

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

swag init

集成到CI/CD流程

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

在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

自动化测试和部署

在CI/CD流程中，确保在生成API文档后执行自动化测试和部署。例如，使用Jenkins或Drone在生成文档后执行单元测试和集成测试。

监控和反馈

配置监控工具（如Prometheus、Grafana）对生产环境进行实时监控，并将监控数据反馈给开发团队和运维团队，以便及时处理问题。

通过以上步骤，你可以将Swagger API文档集成到Linux环境下的CI/CD流程中，确保API文档在每次构建和部署时自动更新，从而提高开发效率和软件质量。