Spring Boot 3.2.8兼容的springdoc-openapi版本咨询及Swagger UI访问问题

开发者阿泽

2026-6-20

与Spring Boot 3.2.8兼容的springdoc-openapi版本推荐

Spring Boot 3.x 版本必须搭配 springdoc-openapi v2.x 系列使用，v1.x 系列仅适配 Spring Boot 2.x，这是你当前用1.7.0版本无法打开Swagger UI的核心原因。

与Spring Boot 3.2.8兼容的稳定版本推荐：

2.5.0：经过广泛验证，适配Spring Boot 3.2.x全系列，功能稳定
2.6.0：最新稳定版，支持更多OpenAPI 3.1特性，同样兼容Spring Boot 3.2.8

替换后的pom.xml依赖配置示例：

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

注意：Spring Boot 3.x 环境下需使用springdoc-openapi-starter-webmvc-ui（WebFlux场景用springdoc-openapi-starter-webflux-ui），而非旧版的springdoc-openapi-ui依赖包。

若替换版本后仍无法访问Swagger UI，可排查以下内容：

确认访问地址为http://localhost:你的项目端口/swagger-ui.html

若项目集成了Spring Security，需放行Swagger相关路径：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
            .requestMatchers("/swagger-ui/**", "/v3/api-docs/**")
            .permitAll()
            .anyRequest().authenticated()
    );
    return http.build();
}