Spring Boot2.7中如何配置swagger-ui.html映射优先级与/v3/api-docs一致？

问题根源 #

在Spring Boot 2.7 + springdoc-openapi-ui 1.6的环境下，/v3/api-docs对应的映射器（OpenApiWebMvcResource）默认优先级高于Swagger UI的映射器（SwaggerWelcomeWebMvc）。而Spring Integration HTTP的入站组件优先级恰好介于两者之间，导致它会拦截/swagger-ui.html的请求，却不会影响/v3/api-docs的访问，最终出现文档可访问但UI无法加载的情况。

调整优先级的配置方案 #

你可以通过自定义处理器映射，让Swagger UI的映射优先级和/v3/api-docs保持一致：

1. 自定义Swagger UI处理器映射类 #

创建一个配置类，手动注册Swagger UI的映射规则并设置优先级：

import org.springdoc.webmvc.ui.SwaggerWelcomeWebMvc;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.handler.SimpleUrlHandlerMapping;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;

import java.util.Collections;
import java.util.Properties;

@Configuration
public class SwaggerUiPriorityConfig {

    @Bean
    public SimpleUrlHandlerMapping swaggerUiHandlerMapping(SwaggerWelcomeWebMvc swaggerWelcomeWebMvc) {
        SimpleUrlHandlerMapping mapping = new SimpleUrlHandlerMapping();
        // 设置与/v3/api-docs相同的优先级（默认RequestMappingHandlerMapping优先级为0）
        mapping.setOrder(RequestMappingHandlerMapping.DEFAULT_ORDER);
        mapping.setUrlMap(Collections.singletonMap("/swagger-ui.html", swaggerWelcomeWebMvc));
        mapping.setMappings(new Properties());
        return mapping;
    }
}

2. 排除自动配置的Swagger UI映射器（可选） #

如果上述配置未生效，需要排除springdoc自动配置的SwaggerUiWebMvcConfigurer，避免映射规则冲突：

import org.springdoc.webmvc.ui.SwaggerUiWebMvcConfigurer;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
@EnableAutoConfiguration(exclude = {SwaggerUiWebMvcConfigurer.class})
public class WebConfig implements WebMvcConfigurer {
    // 其他WebMvc配置内容
}

验证方式 #

启动项目后访问/swagger-ui.html，确认页面正常加载。也可以开启org.springframework.web.servlet.handler的DEBUG日志级别，查看处理器映射的优先级排序，确认Swagger UI的映射器优先级与/v3/api-docs一致。

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