Spring Boot 3集成Swagger失败：无法访问Swagger UI求助

一、版本兼容性确认 #

你的配置中，Spring Boot 3.2.0搭配springdoc-openapi-starter-webmvc-ui 2.6.0属于官方兼容组合，但Java 23为新发布版本，部分依赖可能存在适配延迟。优先从配置、依赖层面排查，暂无需急着降级Java或Spring Boot。

二、关键排查与修复步骤 #

1. 检查启动日志 #

启动应用时重点查看日志：

• 是否存在springdoc、OpenAPI相关的初始化记录
• 是否有类加载异常、依赖冲突报错

若日志中无任何springdoc相关内容，说明依赖未被正确识别或加载。

2. 重构依赖与缓存清理 #

执行Maven命令清理缓存并重新构建，确保依赖完整加载：

mvn clean install -U

3. 添加OpenAPI配置类 #

Spring Boot 3.x + springdoc需要显式配置OpenAPI实例，否则无法生成接口文档。创建如下配置类：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Boot Postgres API")
                        .version("0.0.1-SNAPSHOT")
                        .description("API文档说明"));
    }
}

4. 验证访问路径 #

• 未配置server.servlet.context-path时，正确地址为：
  • Swagger UI：http://localhost:8080/swagger-ui/index.html
  • API文档JSON：http://localhost:8080/v3/api-docs
• 若配置了上下文路径（如/api），需在地址前追加路径，例如http://localhost:8080/api/swagger-ui/index.html

5. 排查Java版本适配问题 #

若以上步骤无效，可临时降级Java版本至Java 21（Spring Boot 3.x官方推荐LTS版本），验证是否为Java 23的兼容性问题。

三、常见坑点排查 #

• 确保spring-boot-starter-web依赖存在，springdoc依赖需Web环境支持
• 若有自定义拦截器/过滤器，需放行以下路径：
  • /swagger-ui/**
  • /v3/api-docs/**
• 若使用Spring Security，需配置放行Swagger资源：

import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityCustomizer;
import org.springframework.context.annotation.Bean;

@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public WebSecurityCustomizer webSecurityCustomizer() {
        return (web) -> web.ignoring().requestMatchers("/swagger-ui/**", "/v3/api-docs/**");
    }
}

内容的提问来源于stack exchange，提问作者MsA