Swagger UI访问报错：No handler found及SimpleUrlHandlerMapping Bean未注入问题排查求助

Hey there, let's tackle this frustrating Swagger UI issue you're dealing with. It's super odd that rolling back to a confirmed working branch still doesn't fix things—so let's break down the most likely causes and actionable fixes step by step:

1. Clear All Spring & Build Caches First #

Since you suspect Spring internal caching is the culprit, start with a full cache wipe:

• Build tool caches:
  • For Maven: Run mvn clean install -U (the -U flag forces dependency updates)
  • For Gradle: Run ./gradlew clean build --refresh-dependencies
• IDE caches: In your IDE (IntelliJ/Eclipse), use the "Invalidate Caches / Restart" option to clear cached class files and metadata.
• Spring Boot DevTools cache: If you're using DevTools, delete the .spring-boot-devtools directory in your user home, or check for a .spring-boot-devtools.properties file that might be overriding settings.

2. Verify Swagger AutoConfiguration Isn't Excluded #

Double-check if Swagger's auto-configuration is accidentally being excluded:

• Look for @SpringBootApplication(exclude = {SwaggerAutoConfiguration.class}) in your main application class.
• Check your application.yml/application.properties for spring.autoconfigure.exclude entries that might list Swagger-related configs.
• Confirm your Swagger starter dependency (like springfox-boot-starter) is correctly included in your build file, with the exact same version as your working service.

3. Manually Register the SimpleUrlHandlerMapping Bean #

If Spring isn't auto-creating the required bean, force it with a custom configuration class:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.web.servlet.handler.SimpleUrlHandlerMapping;
import org.springframework.web.servlet.resource.ResourceHttpRequestHandler;

import java.util.Collections;
import java.util.Arrays;

@Configuration
public class SwaggerUiHandlerConfig {
    @Bean
    public SimpleUrlHandlerMapping swaggerUiHandlerMapping() {
        SimpleUrlHandlerMapping mapping = new SimpleUrlHandlerMapping();
        mapping.setOrder(Integer.MAX_VALUE - 1);

        ResourceHttpRequestHandler resourceHandler = new ResourceHttpRequestHandler();
        resourceHandler.setLocations(Arrays.asList(
                new ClassPathResource("META-INF/resources/"),
                new ClassPathResource("META-INF/resources/webjars/")
        ));

        mapping.setUrlMap(Collections.singletonMap("/swagger-ui.html", resourceHandler));
        return mapping;
    }
}

This explicitly creates the bean Swagger UI needs to serve the HTML page.

4. Check Custom WebMvcConfigurer for Resource Mapping Issues #

If you have a custom WebMvcConfigurer that overrides resource handling, make sure it includes Swagger's static resource paths:

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // Add Swagger UI resource mappings
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        
        // Keep your other resource mappings here
    }
}

A missing or incorrect resource mapping here can block access to Swagger UI.

5. Audit Dependency Conflicts #

Even if you think versions match, run a dependency tree check to rule out hidden conflicts:

• For Maven: mvn dependency:tree
• For Gradle: ./gradlew dependencies
  Look for mismatched versions of springfox modules, or conflicts between Spring Web and Swagger dependencies that might prevent the bean from being created.

6. Check Active Spring Profiles #

If your Swagger configuration uses @Profile("dev") (or another profile), confirm the correct profile is active:

• Check application.yml/application.properties for spring.profiles.active
• Verify your run configuration (in IDE or deployment) isn't setting an unexpected profile that skips Swagger's config.

Debugging Next Step #

If none of the above works, enable debug logging for Spring's auto-configuration to get more context:
Add this to your application.properties:

logging.level.org.springframework.boot.autoconfigure=DEBUG

This will log exactly which auto-config classes are being loaded (and which are being skipped), helping you pinpoint why SimpleUrlHandlerMapping isn't being created.

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