当前位置：首页 > news >正文

SpringDoc OpenAPI集成spring boot3

news 2025/9/12 10:42:37

SpringDoc OpenAPI集成spring boot3

一、简介

SpringDoc OpenAPI 是一个基于 OpenAPI 3 规范的 Java 库，用于自动生成 Spring Boot 应用的 API 文档。它是 Springfox Swagger 的替代品，具有以下优势：

官方推荐：Spring 团队推荐的 API 文档解决方案
零配置：自动发现 Spring MVC 端点，无需复杂配置
性能更好：启动速度比 Springfox 快
支持最新标准：完整支持 OpenAPI 3.0 规范
丰富功能：支持 Spring WebFlux、Spring Security 等

二、实操

1、Pom依赖：

如果你的项目用的是web-services

有这样的依赖：

那么使用

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.8.13</version>
</dependency>

如果你是流式响应：

那么使用；

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webflux-ui</artifactId><version>2.8.13</version>
</dependency>

2、application.properties配置

# Swagger
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/v3/api-docs

3、配置文件

新建OpenApiConfig文件

@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文档").version("2.0").description("基于 SpringDoc OpenAPI 2.8.13 的接口文档").license(new License().name("Apache 2.0").url("https://springdoc.org")));}
}

如配置了Security则需要配置放行

public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {// SpringDoc OpenAPI 相关的放行路径String[] openApiPaths = {"/swagger-ui.html","/swagger-ui/**","/v3/api-docs/**","/swagger-resources/**","/webjars/**","/favicon.ico"};return http.csrf(ServerHttpSecurity.CsrfSpec::disable).authorizeExchange(exchanges -> exchanges// 放行 OpenAPI 相关路径.pathMatchers(openApiPaths).permitAll()// 放行你的前端 API 路径.pathMatchers("/**").permitAll()// 其他路径需要认证.anyExchange().authenticated()).httpBasic(ServerHttpSecurity.HttpBasicSpec::disable).formLogin(ServerHttpSecurity.FormLoginSpec::disable).build();
}

4、控制层设置信息

@RestController@Tag(name = "用户管理", description = "用户相关操作API")@RequestMapping("/api/users")public class UserController {@Operation(summary = "获取用户列表", description = "返回所有用户信息")@GetMappingpublic List<User> getAllUsers() {// 实现}@Operation(summary = "创建用户", description = "创建新用户")@ApiResponses({@ApiResponse(responseCode = "201", description = "用户创建成功"),@ApiResponse(responseCode = "400", description = "无效输入")})@PostMappingpublic ResponseEntity<User> createUser(@Parameter(description = "用户对象", required = true)@RequestBody User user) {// 实现}}

5、实体类中设置信息

@Schema(description = "用户实体")public class User {@Schema(description = "用户ID", example = "1")private Long id;@Schema(description = "用户名", required = true, example = "john_doe")private String username;@Schema(description = "邮箱地址", format = "email")private String email;// getters/setters}

启动springboot项目后，控制台会打印出以下，证明OpenApi 服务启动

在浏览器访问

https://localhost:9000/swagger-ui/index.html

如果没有配置ssl

就访问

http://localhost:9000/swagger-ui/index.html

如图，集成成功

三、分组配置

在OpenApiConfig文件，

@Bean
public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文档").version("2.0").description("基于 SpringDoc OpenAPI 2.8.13 的接口文档").license(new License().name("Apache 2.0").url("https://springdoc.org")))// === 关键：配置Swagger UI的分组下拉框 ===.extensions(Map.of("x-group-config", Map.of("urls", List.of(Map.of("name", "删除操作", "url", "/v3/api-docs/delete-api"),Map.of("name", "聊天操作", "url", "/v3/api-docs/chat-api")))));
}

// === 分组配置 ===
@Bean
public GroupedOpenApi deleteApiGroup() {return GroupedOpenApi.builder().group("delete-api") // 分组标识（URL用）.displayName("删除操作") // UI显示名称（中文）.pathsToMatch("/chat/delete/**") // 匹配删除接口.build();
}@Bean
public GroupedOpenApi chatApiGroup() {return GroupedOpenApi.builder().group("chat-api") // 分组标识（URL用）.displayName("聊天操作") // UI显示名称（中文）.pathsToMatch("/chat/**") // 匹配所有聊天接口.pathsToExclude("/chat/delete/**") // 排除删除接口.build();
}

如图显示：