Create RestClient documentation placeholder

This commit creates a placeholder for future RestClient reference
documentation. It also creats a link to RestClient from the RestTemplate
javadoc.

See gh-30826

Author: poutsma

framework-docs/modules/ROOT/pages/integration/rest-clients.adoc

@@ -3,11 +3,19 @@
 
 The Spring Framework provides the following choices for making calls to REST endpoints:
 
+* xref:integration/rest-clients.adoc#rest-restclient[`RestClient`] - synchronous client with a fluent API.
 * xref:integration/rest-clients.adoc#rest-webclient[`WebClient`] - non-blocking, reactive client with fluent API.
 * xref:integration/rest-clients.adoc#rest-resttemplate[`RestTemplate`] - synchronous client with template method API.
 * xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] - annotated interface with generated, dynamic proxy implementation.
 
 
+[[rest-restclient]]
+== `RestClient`
+
+Reference documentation is forthcoming.
+For now, please refer to the https://docs.spring.io/spring-framework/docs/6.1.0-M1/javadoc-api/org/springframework/web/client/RestClient.html[API documentation].
+
+
 [[rest-webclient]]
 == `WebClient`
 
@@ -36,9 +44,8 @@ The `RestTemplate` provides a higher level API over HTTP client libraries. It ma
 easy to invoke REST endpoints in a single line. It exposes the following groups of
 overloaded methods:
 
-NOTE: `RestTemplate` is in maintenance mode, with only requests for minor
-changes and bugs to be accepted. Please, consider using the
-xref:web/webflux-webclient.adoc[WebClient] instead.
+NOTE: The xref:integration/rest-clients.adoc#rest-restclient[`RestClient`] offers a more modern API for synchronous HTTP access.
+For asynchronous and streaming scenarios, consider the reactive xref:web/webflux-webclient.adoc[WebClient].
 
 [[rest-overview-of-resttemplate-methods-tbl]]
 .RestTemplate methods

framework-docs/modules/ROOT/pages/web/webmvc-client.adoc

@@ -6,43 +6,34 @@ This section describes options for client-side access to REST endpoints.
 
 
 
-[[webmvc-resttemplate]]
-== `RestTemplate`
-
-`RestTemplate` is a synchronous client to perform HTTP requests. It is the original
-Spring REST client and exposes a simple, template-method API over underlying HTTP client
-libraries.
+[[webmvc-restclient]]
+== `RestClient`
 
-NOTE: As of 5.0 the `RestTemplate` is in maintenance mode, with only requests for minor
-changes and bugs to be accepted. Please, consider using the
-xref:web/webflux-webclient.adoc[WebClient] which offers a more modern API and
-supports sync, async, and streaming scenarios.
+`RestClient` is a synchronous HTTP client that exposes a modern, fluent API.
 
-See xref:integration/rest-clients.adoc[REST Endpoints] for details.
+See xref:integration/rest-clients.adoc#rest-restclient[`RestClient`] for more details.
 
 
 
 
 [[webmvc-webclient]]
 == `WebClient`
 
-`WebClient` is a non-blocking, reactive client to perform HTTP requests. It was
-introduced in 5.0 and offers a modern alternative to the `RestTemplate`, with efficient
-support for both synchronous and asynchronous, as well as streaming scenarios.
+`WebClient` is a reactive client to perform HTTP requests with a fluent API.
+
+See xref:web/webflux-webclient.adoc[WebClient] for more details.
 
-In contrast to `RestTemplate`, `WebClient` supports the following:
 
-* Non-blocking I/O.
-* Reactive Streams back pressure.
-* High concurrency with fewer hardware resources.
-* Functional-style, fluent API that takes advantage of Java 8 lambdas.
-* Synchronous and asynchronous interactions.
-* Streaming up to or streaming down from a server.
 
-See xref:web/webflux-webclient.adoc[WebClient] for more details.
 
+[[webmvc-resttemplate]]
+== `RestTemplate`
 
+`RestTemplate` is a synchronous client to perform HTTP requests. It is the original
+Spring REST client and exposes a simple, template-method API over underlying HTTP client
+libraries.
 
+See xref:integration/rest-clients.adoc[REST Endpoints] for details.
 
 [[webmvc-http-interface]]
 == HTTP Interface

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

@@ -89,10 +89,10 @@
  * instances may use the same underlying {@link ClientHttpRequestFactory}
  * if they need to share HTTP client resources.
  *
- * <p><strong>NOTE:</strong> As of 5.0 this class is in maintenance mode, with
- * only minor requests for changes and bugs to be accepted going forward. Please,
- * consider using the {@code org.springframework.web.reactive.client.WebClient}
- * which has a more modern API and supports sync, async, and streaming scenarios.
+ * <p><strong>NOTE:</strong> As of 6.1, {@link RestClient} offers a more modern
+ * API for synchronous HTTP access. For asynchronous and streaming scenarios,
+ * consider the reactive
+ * {@link org.springframework.web.reactive.function.client.WebClient}.
  *
  * @author Arjen Poutsma
  * @author Brian Clozel