Update docs on WebClient filters

Author: rstoyanchev

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

@@ -116,7 +116,8 @@ public interface WebClient {
 
 
 	/**
-	 * Return a builder to mutate properties of this web client.
+	 * Return a builder for a new {@code WebClient} with properties replicated
+	 * from the current {@code WebClient} instance, but without affecting it.
 	 */
 	Builder mutate();
 
@@ -136,6 +137,7 @@ static WebClient create() {
 	 * A variant of {@link #create()} that accepts a default base URL. For more
 	 * details see {@link Builder#baseUrl(String) Builder.baseUrl(String)}.
 	 * @param baseUrl the base URI for all requests
+	 * @see #builder()
 	 */
 	static WebClient create(String baseUrl) {
 		return new DefaultWebClientBuilder().baseUrl(baseUrl).build();

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

@@ -322,44 +322,77 @@ build a new `WebClient`, based on, but without affecting the current instance:
 
 
 [[webflux-client-filter]]
-== Filters
+== Client Filters
 
-`WebClient` supports interception style request filtering:
+You can register an `ExchangeFilterFunction` in the `WebClient.Builder` to intercept and
+possibly modify requests performed through the client:
 
 [source,java,intent=0]
 [subs="verbatim,quotes"]
 ----
-	WebClient client = WebClient.builder()
-			.filter((request, next) -> {
-				ClientRequest filtered = ClientRequest.from(request)
-						.header("foo", "bar")
-						.build();
-				return next.exchange(filtered);
-			})
-			.build();
+WebClient client = WebClient.builder()
+		.filter((request, next) -> {
+
+			ClientRequest filtered = ClientRequest.from(request)
+					.header("foo", "bar")
+					.build();
+
+			return next.exchange(filtered);
+		})
+		.build();
 ----
 
-`ExchangeFilterFunctions` provides a filter for basic authentication:
+This can be used for cross-cutting concerns such as authentication. The example below uses
+a filter for basic authentication through a static factory method:
 
 [source,java,intent=0]
 [subs="verbatim,quotes"]
 ----
 
-	// static import of ExchangeFilterFunctions.basicAuthentication
+// static import of ExchangeFilterFunctions.basicAuthentication
 
-	WebClient client = WebClient.builder()
-			.filter(basicAuthentication("user", "pwd"))
-			.build();
+WebClient client = WebClient.builder()
+		.filter(basicAuthentication("user", "password"))
+		.build();
 ----
 
-You can also mutate an existing `WebClient` instance without affecting the original:
+Filters apply globally to every request. To change how a filter's behavior for a specific
+request, you can add request attributes to the `ClientRequest` that can then be accessed
+by all filters in the chain:
 
 [source,java,intent=0]
 [subs="verbatim,quotes"]
 ----
-	WebClient filteredClient = client.mutate()
-			.filter(basicAuthentication("user", "pwd")
-			.build();
+WebClient client = WebClient.builder()
+		.filter((request, next) -> {
+			Optional<Object> usr = request.attribute("myAttribute");
+			// ...
+		})
+		.build();
+
+client.get().uri("http://example.org/")
+		.attribute("myAttribute", "...")
+		.retrieve()
+		.bodyToMono(Void.class);
+
+	}
+----
+
+You can also replicate an existing `WebClient`, and insert new filters or remove already
+registered filters. In the example below, a basic authentication filter is inserted at
+index 0:
+
+[source,java,intent=0]
+[subs="verbatim,quotes"]
+----
+
+// static import of ExchangeFilterFunctions.basicAuthentication
+
+WebClient client = webClient.mutate()
+		.filters(filterList -> {
+			filterList.add(0, basicAuthentication("user", "password"));
+		})
+		.build();
 ----