From ab94c7c016dbba6a6990294770dd4dd4eba961f9 Mon Sep 17 00:00:00 2001
From: Rossen Stoyanchev <rstoyanchev@vmware.com>
Date: Fri, 5 Feb 2021 13:04:33 +0000
Subject: [PATCH] Update WebMvcConfigurer Javadoc for message converters

Closes gh-26388
---
 .../reactive/config/WebFluxConfigurer.java    | 13 +++++----
 .../config/annotation/WebMvcConfigurer.java   | 27 +++++++++++--------
 2 files changed, 24 insertions(+), 16 deletions(-)

diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/config/WebFluxConfigurer.java b/spring-webflux/src/main/java/org/springframework/web/reactive/config/WebFluxConfigurer.java
index 6bfabed26a..fc8c91ff71 100644
--- a/spring-webflux/src/main/java/org/springframework/web/reactive/config/WebFluxConfigurer.java
+++ b/spring-webflux/src/main/java/org/springframework/web/reactive/config/WebFluxConfigurer.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -93,10 +93,13 @@ public interface WebFluxConfigurer {
 	}
 
 	/**
-	 * Configure custom HTTP message readers and writers or override built-in ones.
-	 * <p>The configured readers and writers will be used for both annotated
-	 * controllers and functional endpoints.
-	 * @param configurer the configurer to use
+	 * Configure the HTTP message readers and writers for reading from the
+	 * request body and for writing to the response body in annotated controllers
+	 * and functional endpoints.
+	 * <p>By default, all built-in readers and writers are configured as long as
+	 * the corresponding 3rd party libraries such Jackson JSON, JAXB2, and others
+	 * are present on the classpath.
+	 * @param configurer the configurer to customize readers and writers
 	 */
 	default void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
 	}
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.java
index 25524520b3..7ec8ac81d8 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.java
@@ -161,23 +161,28 @@ public interface WebMvcConfigurer {
 	}
 
 	/**
-	 * Configure the {@link HttpMessageConverter HttpMessageConverters} to use for reading or writing
-	 * to the body of the request or response. If no converters are added, a
-	 * default list of converters is registered.
-	 * <p><strong>Note</strong> that adding converters to the list, turns off
-	 * default converter registration. To simply add a converter without impacting
-	 * default registration, consider using the method
-	 * {@link #extendMessageConverters(java.util.List)} instead.
+	 * Configure the {@link HttpMessageConverter HttpMessageConverter}s for
+	 * reading from the request body and for writing to the response body.
+	 * <p>By default, all built-in converters are configured as long as the
+	 * corresponding 3rd party libraries such Jackson JSON, JAXB2, and others
+	 * are present on the classpath.
+	 * <p><strong>Note</strong> use of this method turns off default converter
+	 * registration. Alternatively, use
+	 * {@link #extendMessageConverters(java.util.List)} to modify that default
+	 * list of converters.
 	 * @param converters initially an empty list of converters
 	 */
 	default void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
 	}
 
 	/**
-	 * A hook for extending or modifying the list of converters after it has been
-	 * configured. This may be useful for example to allow default converters to
-	 * be registered and then insert a custom converter through this method.
-	 * @param converters the list of configured converters to extend.
+	 * Extend or modify the list of converters after it has been, either
+	 * {@link #configureMessageConverters(List) configured} or initialized with
+	 * a default list.
+	 * <p>Note that the order of converter registration is important. Especially
+	 * in cases where clients accept {@link org.springframework.http.MediaType#ALL}
+	 * the converters configured earlier will be preferred.
+	 * @param converters the list of configured converters to be extended
 	 * @since 4.1.3
 	 */
 	default void extendMessageConverters(List<HttpMessageConverter<?>> converters) {