Deprecate context method in WebClient

See gh-25710

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/DefaultWebClient.java

@@ -306,6 +306,7 @@ public RequestBodySpec attributes(Consumer<Map<String, Object>> attributesConsum
 		}
 
 		@Override
+		@SuppressWarnings("deprecation")
 		public RequestBodySpec context(Function<Context, Context> contextModifier) {
 			this.contextModifier = (this.contextModifier != null ?
 					this.contextModifier.andThen(contextModifier) : contextModifier);

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java

@@ -474,14 +474,14 @@ interface RequestHeadersSpec<S extends RequestHeadersSpec<S>> {
 		S attributes(Consumer<Map<String, Object>> attributesConsumer);
 
 		/**
-		 * Provide a function to populate the Reactor {@code Context}. In contrast
-		 * to {@link #attribute(String, Object) attributes} which apply only to
-		 * the current request, the Reactor {@code Context} transparently propagates
-		 * to the downstream processing chain which may include other nested or
-		 * successive calls over HTTP or via other reactive clients.
+		 * Provide a function to populate the Reactor {@code Context}.
 		 * @param contextModifier the function to modify the context with
+		 * @deprecated in 5.3.2 to be removed soon after; this method cannot
+		 * provide context to downstream (nested or subsequent) requests and is
+		 * of limited value.
 		 * @since 5.3.1
 		 */
+		@Deprecated
 		S context(Function<Context, Context> contextModifier);
 
 		/**

src/docs/asciidoc/web/webflux-webclient.adoc

@@ -951,6 +951,11 @@ For example:
 				.awaitBody<Unit>()
 ----
 
+Note that you can configure a `defaultRequest` callback globally at the
+`WebClient.Builder` level which lets you insert attributes into all requests,
+which could be used for example in a Spring MVC application to populate
+request attributes based on `ThreadLocal` data.
+
 
 [[webflux-client-context]]
 == Context
@@ -960,10 +965,8 @@ chain but they only influence the current request. If you want to pass informati
 propagates to additional requests that are nested, e.g. via `flatMap`, or executed after,
 e.g. via `concatMap`, then you'll need to use the Reactor `Context`.
 
-`WebClient` exposes a method to populate the Reactor `Context` for a given request.
-This information is available to filters for the current request and it also propagates
-to subsequent requests or other reactive clients participating in the downstream
-processing chain. For example:
+The Reactor `Context` needs to be populated at the end of a reactive chain in order to
+apply to all operations. For example:
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
@@ -977,18 +980,14 @@ processing chain. For example:
 			.build();
 
 	client.get().uri("https://example.org/")
-			.context(context -> context.put("foo", ...))
 			.retrieve()
 			.bodyToMono(String.class)
 			.flatMap(body -> {
 					// perform nested request (context propagates automatically)...
-			});
+			})
+			.contextWrite(context -> context.put("foo", ...));
 ----
 
-Note that you can also specify how to populate the context through the `defaultRequest`
-method at the level of the `WebClient.Builder` and that applies to all requests.
-This could be used for to example to pass information from `ThreadLocal` storage onto
-a Reactor processing chain in a Spring MVC application.
 
 
 [[webflux-client-synchronous]]