Spring Boot 3集成springdoc-openapi加载远程配置失败求助

数据老陈

2026-6-29

问题原因及解决方法

核心原因

你自定义了OpenAPI文档的路径为/api-docs，但swagger-ui默认会请求/v3/api-docs/swagger-config加载配置，路径不匹配导致加载失败，同时触发日志中的映射缺失警告。

解决步骤

1. 同步配置swagger-ui的config路径

在application.yml中添加swagger-ui的config-url配置，让它指向自定义api-docs路径下的swagger-config：

springdoc:
  api-docs:
    enabled: true
    path: /api-docs
  swagger-ui:
    config-url: /api-docs/swagger-config

2. 检查拦截/安全配置（如果有）

如果项目中使用了Spring Security或自定义拦截器，需要确保放行以下路径：

/api-docs/**
/swagger-ui/**
/swagger-ui.html（按需添加）

以Spring Security为例，配置示例：

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