Document synchronous use of the WebClient

Fixes #22173

spring-web/src/main/java/org/springframework/web/client/RestTemplate.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -77,7 +77,8 @@ import org.springframework.web.util.UriTemplateHandler;
  * modern alternative to the {@code RestTemplate} with efficient support for
  * both sync and async, as well as streaming scenarios. The {@code RestTemplate}
  * will be deprecated in a future version and will not have major new features
- * added going forward.
+ * added going forward. See the WebClient section of the Spring Framework reference
+ * documentation for more details and example code.
  *
  * @author Arjen Poutsma
  * @author Brian Clozel

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

@@ -591,6 +591,58 @@ WebClient client = webClient.mutate()
 
 
 
+[[webflux-client-synchronous]]
+== Synchronous Use
+
+`WebClient` can be used in synchronous style by blocking at the end for the result:
+
+[source,java,intent=0]
+[subs="verbatim,quotes"]
+----
+Person person = client.get().uri("/person/{id}", i).retrieve()
+	.bodyToMono(Person.class)
+	.block();
+
+List<Person> persons = client.get().uri("/persons").retrieve()
+	.bodyToFlux(Person.class)
+	.collectList()
+	.block();
+----
+
+However if multiple calls need to be made, it's more efficient to avoid blocking on each
+response individually, and instead wait for the combined result:
+
+[source,java,intent=0]
+[subs="verbatim,quotes"]
+----
+Mono<Person> personMono = client.get().uri("/person/{id}", personId)
+		.retrieve().bodyToMono(Person.class);
+
+Mono<List<Hobby>> hobbiesMono = client.get().uri("/person/{id}/hobbies", personId)
+		.retrieve().bodyToFlux(Hobby.class).collectList();
+
+Map<String, Object> data = Mono.zip(personMono, hobbiesMono, (person, hobbies) -> {
+			Map<String, String> map = new LinkedHashMap<>();
+			map.put("person", personName);
+			map.put("hobbies", hobbies);
+			return map;
+		})
+		.block();
+----
+
+The above is merely one example. There are lots of other patterns and operators for putting
+together a reactive pipeline that makes many remote calls, potentially some nested,
+inter-dependent, without ever blocking until the end.
+
+[NOTE]
+====
+You should never have to block in a Spring MVC controller. Simply return the resulting
+`Flux` or `Mono` from the controller method.
+====
+
+
+
+
 [[webflux-client-testing]]
 == Testing
 

src/docs/asciidoc/web/webmvc-client.adoc

@@ -14,9 +14,11 @@ Spring REST client and exposes a simple, template-method API over underlying HTT
 libraries.
 
 NOTE: As of 5.0, the non-blocking, reactive `WebClient` offers a modern alternative to the
-`RestTemplate`, with efficient support for both synchronous and asynchronous, as well as streaming
+`RestTemplate`, with efficient support for both
-scenarios. The `RestTemplate` will be deprecated in a future version and will not have
+<<web-reactive.adoc#webflux-client-synchronous,synchronous and asynchronous>>, as well as
-major new features added going forward.
+streaming scenarios. The `RestTemplate` will be deprecated in a future version and will
+not have major new features added going forward.
+
 
 See <<integration.adoc#rest-client-access,REST Endpoints>> for details.