本地Spring Boot v2.17无法访问OpenAPI文档及Swagger UI页面求助

1. 优先排查版本兼容性问题 #

SpringDoc 1.7.0适配的Spring Boot版本范围是2.4.x至2.7.x，而你使用的是Spring Boot v2.1.7，版本不匹配是导致映射无法注册的核心原因。低版本Spring Boot无法兼容高版本SpringDoc组件。

解决方案：

• 降级SpringDoc到适配Spring Boot 2.1.x的稳定版本（如1.1.49），修改pom.xml依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.1.49</version>
</dependency>
<!-- 1.1.x版本中无需单独引入springdoc-openapi-webmvc-core，已包含在ui依赖内 -->

2. 检查自定义拦截器/过滤器是否拦截请求 #

若项目存在自定义HandlerInterceptor或Filter，可能会拦截SpringDoc的请求路径：

• 检查配置类中的拦截器注册逻辑，确保放行以下路径：
  • /v3/api-docs/**
  • /swagger-ui/**
  • /swagger-ui.html（1.1.x版本可能使用该路径）
• 示例放行配置：

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(customInterceptor)
            .excludePathPatterns("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html");
}

3. 排查Spring Security权限限制 #

如果项目集成了Spring Security，需配置规则放行SpringDoc相关路径：

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
                .anyRequest().authenticated();
    }
}

4. 确认SpringDoc自动配置未被禁用 #

检查项目是否通过注解或配置禁用了SpringDoc自动配置：

• 查看application.properties中是否存在类似配置：

spring.autoconfigure.exclude=org.springdoc.core.SpringDocConfiguration

若有，移除该配置，让SpringDoc自动注册请求映射。

5. 通过启动日志验证映射注册状态 #

启动应用时，查看控制台日志，搜索Mapping servlet: 'openApiServlet'或Mapped URL path [/v3/api-docs/**]相关内容，确认SpringDoc的映射是否成功注册。如果无相关日志，说明自动配置未生效，需回到前面步骤重新排查。

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