Clarify the effect of using @EnableWebMvc

[sandipchitale]

The following line:

https://github.com/spring-projects/spring-boot/blob/07a7ff473b6e97db6f00eb62f4f8beb2fb8da73b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/web/servlet.adoc?plain=1#L45C1-L45C1

does say (specifically but without @EnableWebMvc) :

If you want to keep those Spring Boot MVC customizations and make more {spring-framework-docs}/web.html#mvc[MVC customizations] (interceptors, formatters, view controllers, and other features), you can add your own @Configuration class of type WebMvcConfigurer but without @EnableWebMvc.

IMO this should be made explicitly crystal clear as to why? Something along the lines of:

If you have a configuration with @EnableWebMvc in your Springboot application that basically instantiates the Spring WebMVC bean DelegatingWebMvcConfiguration which extends WebMvcConfigurationSupport and that trips/fails the @ConditionalOnMissingBean(WebMvcConfigurationSupport.class) annotation on WebMvcAutoConfiguration and it backs off.

I think many users read the section:

Enable MVC Configuration

which seems to tell them to turn on @EnableWebMvc.

I think @EnableWebMvc disabling the Spring Boots MVC autoconfiguration comes across as a confusing double negative to new users.

Once one understands what is going on it makes sense, but I got tripped by it and have seen issues filed and many SO entries.

[snicoll]

Isn't that said two lines below already?

If you want to take complete control of Spring MVC, you can add your own @Configuration annotated with @EnableWebMvc, or alternatively add your own @Configuration-annotated DelegatingWebMvcConfiguration as described in the Javadoc of @EnableWebMvc.

[sandipchitale]

Don't get me wrong. Like I said, once one understands what happened then it all makes sense. Those two lines tell the user what to do if they want full control. i.e. they do not want either Spring Boot auto config nor what pure @EnableWebMvc gives them if they do not have a @Configuration-annotated DelegatingWebMvcConfiguration. Sure.

I think the confusion happens when they do not want to take full control but want the Spring boot provided auto configuration and want to add to it and they do:

@Configuration
@EnableWebMvc // <--------------------- Mistake
public static class MyAdditions implements WebMvcConfigurer {
    // They want add to Springboots Auto config, , but instead they end up adding to Spring MVC provided config.
}

[wilkinsona]

While I don't think we should go into the level of detail suggested above, I do think we could clarify things by mentioning @EnableWebMvc earlier and mentioning that it cannot be used with the auto-configuration. Something like this. Does that address your concern on the Boot side, @sandipchitale?

On the Framework side, there are places in their docs where they mention Spring Boot. The section on @EnableWebMvc feels to me like it would benefit from similar treatment. @sandipchitale, you may want to open a Framework issue for that.

[sandipchitale]

@wilkinsona I agree about not going into details as I suggested. I was just trying to make it very clear. I like what you are capturing and does address my concern. I think it will save users time, assuming of course they read the docs. And I will file a similar issue for framework because I think users reading their docs and Springboot docs was causing some confusion.

[sandipchitale]

I suggest a small addition to:

It replaces the need for @EnableWebMvc and the two cannot be used together, because if you specify @EnableWebMvc, Springboot backs off and does not apply any of it's MVC auto-configuration.

[wilkinsona]

Thanks for the suggestion but I think that's covered a few sentences later by the following:

If you do not want to use the auto-configuration and want to take complete control of Spring MVC, add your own @Configuration annotated with @EnableWebMvc.