升级Spring Security后无法访问Swagger UI的排查与修复咨询

已基于Spring Security完成配置，HTML模板和REST接口可正常访问，但Swagger UI始终返回404，请求路径均提示"...not found"。以下是相关配置信息及尝试情况：

安全配置类 #

@Configuration
public class WebSecurityConfig {

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }


    @Bean
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity httpSecurity) {

        return httpSecurity
                .csrf(ServerHttpSecurity.CsrfSpec::disable)
                .formLogin(ServerHttpSecurity.FormLoginSpec::disable)
                .httpBasic(ServerHttpSecurity.HttpBasicSpec::disable)
                .authorizeExchange(authorizeExchangeSpec ->
                        authorizeExchangeSpec
                                .pathMatchers( "/home").permitAll()
                                /*для endpoints*/
                                .pathMatchers(HttpMethod.POST, "/api/**").permitAll()
                                .pathMatchers(
                                        "/favicon.ico",
                                       "/v3/api-docs/**",
                                        "/swagger-ui.html",
                                        "/actuator/swagger-ui").permitAll()
                                .anyExchange().authenticated()

                )
                .build();
    }
}

依赖信息 #

implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'org.springdoc:springdoc-openapi-webflux-ui:1.7.0'
implementation 'org.springframework:spring-webflux:6.0.9'
implementation 'org.springframework.security:spring-security-web:6.1.0'
implementation 'org.springdoc:springdoc-openapi-security:1.7.0'

application.yml配置 #

CONTEXT_PATH_APP: /context-path

spring:
  webflux:
    base-path: ${CONTEXT_PATH_APP}


springdoc:
  swagger-ui:
    path: /swagger-ui.html
  show-actuator: true
  use-management-port: true

management:
  endpoints:
    web:
      exposure:
        include: openapi, swagger-ui
  server:
    port: 9090

尝试访问的路径及错误 #

• http://localhost:9090/context-path/actuator/swagger-ui → 404
• http://localhost:8091/context-path/swagger-ui → 404
• http://localhost:8091/context-path/v3/api-docs → 返回404：

{
  "status": 404,
  "message": "404 NOT_FOUND",
  "detailMessage": null
}

修复方案及诊断思路 #

1. 修正Spring Security路径匹配（适配base-path） #

应用配置了spring.webflux.base-path=/context-path，但Security的路径匹配未包含该前缀，导致允许访问的路径与实际部署路径不匹配。修改Security配置，补充完整路径前缀及Swagger静态资源路径：

.authorizeExchange(authorizeExchangeSpec ->
        authorizeExchangeSpec
                .pathMatchers( "/home").permitAll()
                .pathMatchers(HttpMethod.POST, "/api/**").permitAll()
                .pathMatchers(
                        "/favicon.ico",
                        "/context-path/v3/api-docs/**",
                        "/context-path/swagger-ui.html",
                        "/context-path/swagger-ui/**", // 新增：Swagger UI加载静态资源需要此路径
                        "/actuator/swagger-ui") // 管理端口路径无需base-path
                .permitAll()
                .anyExchange().authenticated()
)

2. 修正SpringDoc与管理端口的路径配置 #

设置springdoc.use-management-port=true后，Swagger相关端点部署在管理端口（9090），且管理端点不继承应用的base-path，因此正确访问路径应为：

• OpenAPI文档：http://localhost:9090/actuator/openapi
• Swagger UI：http://localhost:9090/actuator/swagger-ui

同步修改application.yml的SpringDoc配置：

springdoc:
  swagger-ui:
    path: /actuator/swagger-ui # 直接绑定到actuator路径
  show-actuator: true
  use-management-port: true

3. 修复版本兼容性问题 #

你使用的Spring WebFlux 6.0.9对应Spring Boot 3.x，但springdoc-openapi-webflux-ui:1.7.0仅适配Spring Boot 2.x，版本不兼容会导致端点无法注册。需升级SpringDoc到适配Spring Boot 3.x的版本：

// 移除旧依赖，替换为starter包
implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.2.0'

4. 验证端点注册状态 #

启动应用后访问http://localhost:9090/actuator，查看已暴露端点列表，确认openapi和swagger-ui是否存在。若未出现，临时修改management配置全量暴露端点排查：

management:
  endpoints:
    web:
      exposure:
        include: "*"

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