Spring Boot 4.0 Migration Guide does not document that replacing the auto-configured mapper requires a JsonMapper bean

[CNeenan]

In Spring Boot 3.x you could fully replace the auto-configured Jackson mapper by declaring your own @Bean ObjectMapper. In Spring Boot 4 the auto-configured mapper is a JsonMapper, and the auto-configuration now backs off only when you declare a bean of type JsonMapper.

Because JsonMapper extends ObjectMapper, an @Bean ObjectMapper no longer replaces it. Both beans remain in the context and the auto-configured JsonMapper stays @Primary, so it continues to be used and the custom ObjectMapper is effectively ignored.

See:
#47379

The Spring Boot 4.0 Migration Guide does not call this out explicitly here:
https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide

It is an easy mistake to hit when upgrading that causes a change in behaviour, for example:

@Bean
ObjectMapper objectMapper() {
    return JsonMapper.builder()
        .addModule(new MyCustomModule())   // silently NOT applied to the mapper actually used
        .build();
}

Changing the bean return type to JsonMapper resolves the issue.

My suggestion is to extend the migration guide to cover this scenario. I'm also happy to open a PR for features/json.adoc if you feel it should be documented there.

[wilkinsona]

I've added a section to the migration guide about format-specific mappers.