SpringBoot集成springdoc异常：OpenAPI文档链接无法访问

问题描述 #

我正在SpringBoot 3.3.1应用中集成springdoc，已添加以下依赖：

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

依赖树如下：

[INFO] +- org.springdoc:springdoc-openapi-starter-webmvc-ui:jar:2.5.0:compile
[INFO] |  +- org.springdoc:springdoc-openapi-starter-webmvc-api:jar:2.5.0:compile
[INFO] |  |  \- org.springdoc:springdoc-openapi-starter-common:jar:2.5.0:compile
[INFO] |  |     \- io.swagger.core.v3:swagger-core-jakarta:jar:2.2.21:compile
[INFO] |  |        +- io.swagger.core.v3:swagger-annotations-jakarta:jar:2.2.21:compile
[INFO] |  |        +- io.swagger.core.v3:swagger-models-jakarta:jar:2.2.21:compile
[INFO] |  |        \- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:jar:2.17.1:compile
[INFO] |  \- org.webjars:swagger-ui:jar:5.13.0:compile

但访问以下链接均提示"This site can’t be reached"：

http://localhost:8080/v3/api-docs
http://localhost:8080/swagger-ui/index.html

请问是否需要额外配置？

排查与解决步骤 #

1. 确认应用状态与端口 #

• 检查SpringBoot应用是否正常启动，控制台无报错
• 核实应用实际监听端口：若通过server.port配置了自定义端口，需替换链接中的8080为实际端口

2. 处理Spring Security拦截（若集成） #

如果项目使用Spring Security，必须放行springdoc相关接口，否则会被拦截：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html")
                .permitAll()
                .anyRequest().authenticated()
        );
        // swagger-ui需要关闭CSRF保护
        http.csrf(csrf -> csrf.disable());
        return http.build();
    }
}

3. 显式配置springdoc路径（可选） #

在application.properties中添加配置，确保路径映射正确（默认配置可省略，若自定义路径需同步修改）：

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

4. 检查应用上下文路径 #

若配置了server.servlet.context-path，需在链接中加上上下文前缀。例如上下文路径为/myapp，则访问链接应为：

http://localhost:8080/myapp/v3/api-docs
http://localhost:8080/myapp/swagger-ui/index.html

5. 验证依赖兼容性 #

SpringBoot 3.3.1与springdoc 2.5.0兼容，若问题仍存在，可尝试升级到最新兼容版本（如2.6.0），排除版本适配问题

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