Mastering Spring Boot WebMvc Customization: From Deprecated Adapters to Modern Configurers

When a colleague removed the @RequestParam annotation, automatic parameter binding in a Spring Boot project stopped working, revealing hidden pitfalls in WebMvc customization.

Default Spring Boot MVC Configuration

Spring Boot provides out‑of‑the‑box MVC settings such as view resolvers, static resource handling, type converters, message converters, and a default home page. These defaults follow the "convention over configuration" principle.

Deprecated Approaches

WebMvcConfigurerAdapter was an abstract class that offered empty method implementations for WebMvcConfigurer. With Java 8, interfaces can define default methods, making the adapter unnecessary. In Spring Boot 2.x the class is marked @Deprecated and should be replaced by directly implementing WebMvcConfigurer.

@Deprecated
public abstract class WebMvcConfigurerAdapter implements WebMvcConfigurer {}

Extending WebMvcConfigurationSupport is another way to customize MVC, but it requires adding @Configuration to the subclass because the class itself does not carry that annotation. Overriding methods such as addInterceptors or addViewControllers works, yet this approach completely replaces Spring Boot’s auto‑configuration, causing static resources, view resolution, and parameter binding to break.

public class WebMvcConfig extends WebMvcConfigurationSupport { ... }

Why Extending WebMvcConfigurationSupport Breaks Defaults

Spring Boot’s WebMvcAutoConfiguration is conditional on the absence of a WebMvcConfigurationSupport bean ( @ConditionalOnMissingBean). When you provide your own subclass, the auto‑configuration class is skipped, and all default MVC features disappear.

@Configuration(proxyBeanMethods = false)
@ConditionalOnMissingBean({WebMvcConfigurationSupport.class})
public class WebMvcAutoConfiguration { ... }

Recommended Solution: Implement WebMvcConfigurer

Implementing WebMvcConfigurer preserves Spring Boot’s defaults while allowing you to add custom behavior. Multiple implementations can coexist; Spring collects them via @Autowired(required = false) into a list and merges their configurations.

@Configuration
public class MyMVCConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/user").setViewName("success");
    }
}

This approach does not trigger the replacement of default settings and is the preferred way to customize MVC.

When to Use @EnableWebMvc

Adding @EnableWebMvc imports DelegatingWebMvcConfiguration, which extends WebMvcConfigurationSupport. Consequently, the presence of this bean prevents WebMvcAutoConfiguration from running, fully disabling Spring Boot’s MVC defaults. Use it only when you need complete control over MVC configuration, and ensure only one class carries the annotation.

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Import(DelegatingWebMvcConfiguration.class)
public @interface EnableWebMvc { }

Common Customizations via WebMvcConfigurer

Static Resources : Override addResourceHandlers to map custom static paths.

Interceptors : Override addInterceptors to register HandlerInterceptor implementations.

CORS : Override addCorsMappings to configure cross‑origin requests.

View Controllers : Override addViewControllers for simple URL‑to‑view mappings.

Message Converters : Override configureMessageConverters to add custom HttpMessageConverter instances.

Formatters : Override addFormatters to register date or number formatters.

View Resolvers : Override configureViewResolvers to set view prefixes, suffixes, and content types.

Summary

Understanding the three ways to customize Spring MVC—deprecated WebMvcConfigurerAdapter, extending WebMvcConfigurationSupport, and implementing WebMvcConfigurer —helps avoid configuration pitfalls. The safest, most flexible method is to implement WebMvcConfigurer, which retains Spring Boot’s auto‑configuration while allowing targeted extensions. Use @EnableWebMvc only for full MVC control, and avoid extending WebMvcConfigurationSupport unless you deliberately want to replace all defaults.