将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
然后在项目根目录下运行以下命令生成文档：
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
4. 自动化测试和部署
在CI/CD流程中，确保在生成API文档后执行自动化测试和部署。例如，使用Jenkins或Drone在生成文档后执行单元测试和集成测试。
5. 监控和反馈
配置监控工具（如Prometheus、Grafana）对生产环境进行实时监控，并将监控数据反馈给开发团队和运维团队，以便及时处理问题。
通过以上步骤，你可以将Swagger API文档集成到Linux环境下的CI/CD流程中，确保API文档在每次构建和部署时自动更新，从而提高开发效率和软件质量。
