Add documentation for interface proxy client

Closes gh-28386

Author: rstoyanchev

src/docs/asciidoc/index.adoc

@@ -14,11 +14,12 @@ JDBC, R2DBC, O/R Mapping, XML Marshalling.
 STOMP Messaging.
 <<web-reactive.adoc#spring-webflux, Web Reactive>> :: Spring WebFlux, WebClient,
 WebSocket, RSocket.
-<<integration.adoc#spring-integration, Integration>> :: JMS, JCA, JMX, Email, Tasks, Scheduling, Caching.
+<<integration.adoc#spring-integration, Integration>> :: REST Clients, JMS, JCA, JMX,
+Email, Tasks, Scheduling, Caching.
 <<languages.adoc#languages, Languages>> :: Kotlin, Groovy, Dynamic Languages.
 <<appendix.adoc#appendix, Appendix>> :: Spring properties.
-https://github.com/spring-projects/spring-framework/wiki[*Wiki*] :: What's New, Upgrade Notes, Supported Versions,
-and other cross-version information.
+https://github.com/spring-projects/spring-framework/wiki[*Wiki*] :: What's New,
+Upgrade Notes, Supported Versions, and other cross-version information.
 
 ifdef::backend-html5[]
 NOTE: This documentation is also available as {docs-spring-framework}/reference/pdf/index.pdf[PDF].

src/docs/asciidoc/integration.adoc

@@ -12,19 +12,34 @@ a number of technologies.
 
 
 [[rest-client-access]]
-== REST Endpoints
+== REST Clients
 
-The Spring Framework provides two choices for making calls to REST endpoints:
+The Spring Framework provides the following choices for making calls to REST endpoints:
+
+* <<rest-webclient>> - non-blocking, reactive client w fluent API.
+* <<rest-resttemplate>> - synchronous client with template method API.
+* <<rest-http-interface>> - annotated interface with generated, dynamic proxy implementation.
+
+
+[[rest-webclient]]
+=== `WebClient`
+
+`WebClient` is a non-blocking, reactive client to perform HTTP requests. It was
+introduced in 5.0 and offers an alternative to the `RestTemplate`, with support for
+synchronous, asynchronous, and streaming scenarios.
+
+`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 <<web-reactive.adoc#webflux-client, WebClient>> for more details.
 
-* <<rest-resttemplate>>: The original Spring REST client with a synchronous, template
-method API.
-* <<web-reactive.adoc#webflux-client, WebClient>>: a non-blocking, reactive alternative
-that supports both synchronous and asynchronous as well as streaming scenarios.
 
-NOTE: As of 5.0 the `RestTemplate` is in maintenance mode, with only minor requests for
-changes and bugs to be accepted going forward. Please, consider using the
-<<web-reactive.adoc#webflux-client, WebClient>> which offers a more modern API and
-supports sync, async, and streaming scenarios.
 
 
 [[rest-resttemplate]]
@@ -34,6 +49,10 @@ 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
+<<web-reactive.adoc#webflux-client, WebClient>> instead.
+
 [[rest-overview-of-resttemplate-methods-tbl]]
 .RestTemplate methods
 [cols="1,3"]
@@ -344,6 +363,151 @@ to `multipart/form-data` by the `FormHttpMessageConverter`. If the `MultiValueMa
 If necessary the `Content-Type` may also be set explicitly.
 
 
+[[rest-http-interface]]
+=== HTTP Interface
+
+The Spring Frameworks lets you define an HTTP service as a Java interface with annotated
+methods for HTTP exchanges. You can then generate a proxy that implements this interface
+and performs the exchanges. This helps to simplify HTTP remote access which often
+involves a facade that wraps the details of using the underlying HTTP client.
+
+To start, declare an interface with annotated, HTTP exchange methods:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	interface RepositoryService {
+
+		@GetExchange("/repos/{owner}/{repo}")
+		Repository getRepository(@PathVariable String owner, @PathVariable String repo);
+
+		// more HTTP exchange methods...
+
+	}
+----
+
+Now you create a proxy for the interface that performs the declared exchanges through
+the `WebClient`:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	WebClient client = WebClient.builder()
+			.baseUrl("https://api.github.com/")
+			.build();
+
+	HttpServiceProxyFactory proxyFactory = 
+			HttpServiceProxyFactory.builder(new WebClientAdapter(client)).build();
+
+	RepositoryService service = proxyFactory.createClient(RepositoryService.class);
+----
+
+An HTTP service interface can declare common attributes at the type level:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	@HttpExchange(url = "/repos/{owner}/{repo}", accept = "application/vnd.github.v3+json")
+	interface RepositoryService {
+
+		@GetExchange
+		Repository getRepository(@PathVariable String owner, @PathVariable String repo);
+
+		@PatchExchange(contentType = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
+		void updateRepository(@PathVariable String owner, @PathVariable String repo,
+				@RequestParam String name, @RequestParam String description, @RequestParam String homepage);
+
+	}
+----
+
+
+[[rest-http-interface-method-parameters]]
+==== Method Parameters
+
+Annotated, HTTP exchange methods support flexible method signatures with the following
+method parameters:
+
+[cols="1,2", options="header"]
+|===
+| Controller method argument | Description
+
+| `URI`
+| Dynamically set the URL for the request, overriding the annotation's `url` attribute.
+
+| `HttpMethod`
+| Dynamically set the HTTP method for the request, overriding the annotation's `method` attribute
+
+| `@RequestHeader`
+| Add a request header or mutliple headers. The argument may be a `Map<String, ?>` or
+  `MultiValueMap<String, ?>` with multiple headers, a `Collection<?>` of values, or an
+  individual value. Type conversion is supported for non-String values.
+
+| `@PathVariable`
+| Add a variable for expand a placeholder in the request URL. The argument may be a
+  `Map<String, ?>` with multiple variables, or an individual value. Type conversion
+  is supported for non-String values.
+
+| `@RequestBody`
+| Provide the body of the request either as an Object to be serialized, or a
+  Reactive Streams `Publisher` such as `Mono`, `Flux`, or any other async type supported
+  through the configured `ReactiveAdapterRegistry`.
+
+| `@RequestParam`
+| Add a request parameter or mutliple parameters. The argument may be a `Map<String, ?>`
+  or `MultiValueMap<String, ?>` with multiple parameters, a `Collection<?>` of values, or
+  an individual value. Type conversion is supported for non-String values.
+  
+  When `"content-type"` is set to `"application/x-www-form-urlencoded"`, request
+  parameters are encoded in the request body. Otherwise, they are added as URL query
+  parameters.
+
+| `@CookieValue`
+| Add a cookie or mutliple cookies. The argument may be a `Map<String, ?>` or
+  `MultiValueMap<String, ?>` with multiple cookies, a `Collection<?>` of values, or an
+  individual value. Type conversion is supported for non-String values.
+
+|===
+
+
+[[rest-http-interface-return-values]]
+==== Return Values
+
+Annotated, HTTP exchange methods support the following return values:
+
+[cols="1,2", options="header"]
+|===
+| Controller method return value | Description
+
+| `void`, `Mono<Void>`
+| Perform the given request, and release the response content, if any.
+
+| `HttpHeaders`, `Mono<HttpHeaders>`
+| Perform the given request, release the response content, if any, and return the
+  response headers.
+
+| `<T>`, `Mono<T>`
+| Perform the given request and decode the response content to the declared return type.
+
+| `<T>`, `Flux<T>`
+| Perform the given request and decode the response content to a stream of the declared
+  element type.
+
+| `ResponseEntity<Void>`, `Mono<ResponseEntity<Void>>`
+| Perform the given request, and release the response content, if any, and return a
+  `ResponseEntity` with the status and headers.
+
+| `ResponseEntity<T>`, `Mono<ResponseEntity<T>>`
+| Perform the given request, decode the response content to the declared return type, and
+  return a `ResponseEntity` with the status, headers, and the decoded body.
+
+| `Mono<ResponseEntity<Flux<T>>`
+| Perform the given request, decode the response content to a stream of the declared
+  element type, and return a `ResponseEntity` with the status, headers, and the decoded
+  response body stream.
+
+|===
+
+TIP: You can also use any other async or reactive types registered in the
+`ReactiveAdapterRegistry`.
+
+
 
 
 [[jms]]

src/docs/asciidoc/web-reactive.adoc

@@ -17,6 +17,18 @@ include::web/webflux.adoc[leveloffset=+1]
 
 include::web/webflux-webclient.adoc[leveloffset=+1]
 
+
+[[webflux-http-interface-client]]
+== HTTP Interface Client
+
+The Spring Frameworks lets you define an HTTP service as a Java interface with HTTP
+exchange methods. You can then generate a proxy that implements this interface and
+performs the exchanges. This helps to simplify HTTP remote access and provides additional
+flexibility for to choose an API style such as synchronous or reactive.
+
+See <<integration.adoc#rest-http-interface, REST Endpoints>> for details.
+
+
 include::web/webflux-websocket.adoc[leveloffset=+1]
 
 

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

@@ -13,8 +13,8 @@ This section describes options for client-side access to REST endpoints.
 Spring REST client and exposes a simple, template-method API over underlying HTTP client
 libraries.
 
-NOTE: As of 5.0 the `RestTemplate` is in maintenance mode, with only minor requests for
-changes and bugs to be accepted going forward. Please, consider using the
+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
 <<web-reactive.adoc#webflux-client, WebClient>> which offers a more modern API and
 supports sync, async, and streaming scenarios.
 
@@ -40,3 +40,16 @@ In contrast to `RestTemplate`, `WebClient` supports the following:
 * Streaming up to or streaming down from a server.
 
 See <<web-reactive.adoc#webflux-client, WebClient>> for more details.
+
+
+
+
+[[webmvc-http-interface]]
+== HTTP Interface
+
+The Spring Frameworks lets you define an HTTP service as a Java interface with HTTP
+exchange methods. You can then generate a proxy that implements this interface and
+performs the exchanges. This helps to simplify HTTP remote access and provides additional
+flexibility for to choose an API style such as synchronous or reactive.
+
+See <<integration.adoc#rest-http-interface, REST Endpoints>> for details.