Repository navigation
Converter overrides in HttpMessageConverters only apply when defaults are registered #36579
Description
/**
* Override the default Jackson 3.x JSON {@code HttpMessageConverter}
* with any converter supporting the JSON format.
* @param jsonMessageConverter the converter instance to use
* @see org.springframework.http.converter.json.JacksonJsonHttpMessageConverter
*/
T withJsonConverter(HttpMessageConverter<?> jsonMessageConverter);I initially looked only at the Javadoc and assumed that overriding the JSON converter would register it unconditionally. After checking the implementation, I found that this is not the case: when registerDefaults() is not enabled, withJsonConverter(...) and similar methods are ignored and no converter is registered.
@Bean
fun groupConfigurer(objectMapper: JsonMapper): RestClientHttpServiceGroupConfigurer =
RestClientHttpServiceGroupConfigurer { groups ->
groups.forEachClient { _, builder ->
builder
.configureMessageConverters {
it.withJsonConverter(JacksonJsonHttpMessageConverter(objectMapper))
}
}
}In this example, the order looks valid at a glance, but the specific converter registration only takes effect if registerDefaults() has already been enabled.
This matches the concern raised in the discussion on issue #35704, where it was
noted that the Javadoc should explicitly state that these format-specific converter
methods are intended to customize default registrations, and are ignored when default
registrations are turned off. That clarification does not appear to be reflected in
the current Javadoc yet.
It would be helpful to update the Javadoc to explicitly document this behavior,
so that users are not misled into expecting unconditional registration.
Activity
bclozel commentedon Apr 1, 2026
I've reviewed the conversation in #35704 and use cases similar to this one.
So far we tried to favor consistency with the reactive codecs, which are organized in two groups,
DefaultCodecsandCustomCodecs. WithHttpMessageConverters, our use cases didn't require this level of indirection because we don't have to offer specific configuration options for each group. This makes the API surface flatter and consider converters as a single collection.Comments in #35704 also point out that the ordering of converters has less meaning if defaults aren't activated. I have changed my mind about this because customizing
HttpMessageConverterscan happen in many independent places and having to callregisterDefaults()in each place (to ensure that our customization is effective) is not consistent with the overall API design.I'm repurposing this issue to adapt the behavior here and not require the registration of defaults when overrides are provided. This also aligns with the existing behavior when using
addCustomConverter.[-]Clarify format-specific converter methods require registerDefaults() in HttpMessageConverters[/-][+]Converter overrides in HttpMessageConverters only apply when defaults are registered[/+]Register overrides in HttpMessageConverters when defaults are off