From e9e19f5ed739eb478ca851804f56db9190559172 Mon Sep 17 00:00:00 2001 From: rstoyanchev Date: Mon, 22 Sep 2025 11:31:32 +0100 Subject: [PATCH] Update references to HTTP service clients in docs Closes gh-35522 --- framework-docs/modules/ROOT/nav.adoc | 2 +- .../ROOT/pages/integration/rest-clients.adoc | 22 +++++++++--------- ....adoc => webflux-http-service-client.adoc} | 6 ++--- .../ROOT/pages/web/webflux-versioning.adoc | 2 +- .../controller/ann-requestmapping.adoc | 23 +++++++++---------- .../modules/ROOT/pages/web/webmvc-client.adoc | 6 ++--- .../ROOT/pages/web/webmvc-versioning.adoc | 2 +- .../mvc-controller/ann-requestmapping.adoc | 9 ++++---- .../CustomHttpServiceArgumentResolver.java | 6 ++--- .../CustomHttpServiceArgumentResolver.kt | 6 ++--- .../service/invoker/HttpRequestValues.java | 2 +- .../registry/HttpServiceProxyRegistry.java | 4 ++-- 12 files changed, 44 insertions(+), 46 deletions(-) rename framework-docs/modules/ROOT/pages/web/{webflux-http-interface-client.adoc => webflux-http-service-client.adoc} (68%) rename framework-docs/src/main/java/org/springframework/docs/integration/{resthttpinterface => resthttpserviceclient}/customresolver/CustomHttpServiceArgumentResolver.java (95%) rename framework-docs/src/main/kotlin/org/springframework/docs/integration/{resthttpinterface => resthttpserviceclient}/customresolver/CustomHttpServiceArgumentResolver.kt (94%) diff --git a/framework-docs/modules/ROOT/nav.adoc b/framework-docs/modules/ROOT/nav.adoc index 06d105e209b..276c84ee663 100644 --- a/framework-docs/modules/ROOT/nav.adoc +++ b/framework-docs/modules/ROOT/nav.adoc @@ -314,7 +314,7 @@ *** xref:web/webflux-webclient/client-context.adoc[] *** xref:web/webflux-webclient/client-synchronous.adoc[] *** xref:web/webflux-webclient/client-testing.adoc[] -** xref:web/webflux-http-interface-client.adoc[] +** xref:web/webflux-http-service-client.adoc[] ** xref:web/webflux-websocket.adoc[] ** xref:web/webflux-test.adoc[] ** xref:rsocket.adoc[] diff --git a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc index 0417613f496..1cf4363b0e5 100644 --- a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc +++ b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc @@ -6,7 +6,7 @@ The Spring Framework provides the following choices for making calls to REST end * 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 Clients] -- annotated interface backed by generated proxy +* xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service Clients] -- annotated interface backed by generated proxy [[rest-restclient]] @@ -855,8 +855,8 @@ It can be used to migrate from the latter to the former. |=== -[[rest-http-interface]] -== HTTP Interface Clients +[[rest-http-service-client]] +== HTTP Service Clients You can define an HTTP Service as a Java interface with `@HttpExchange` methods, and use `HttpServiceProxyFactory` to create a client proxy from it for remote access over HTTP via @@ -928,7 +928,7 @@ Now, you're ready to create client proxies: // Use service methods for remote calls... ---- -[[rest-http-interface-method-parameters]] +[[rest-http-service-client-method-parameters]] === Method Parameters `@HttpExchange` methods support flexible method signatures with the following inputs: @@ -1000,13 +1000,13 @@ parameter annotation) is set to `false`, or the parameter is marked optional as `StreamingHttpOutputMessage.Body` that allows sending the request body by writing to an `OutputStream`. -[[rest-http-interface.custom-resolver]] +[[rest-http-service-client.custom-resolver]] === Custom Arguments You can configure a custom `HttpServiceArgumentResolver`. The example interface below uses a custom `Search` method parameter type: -include-code::./CustomHttpServiceArgumentResolver[tag=httpinterface,indent=0] +include-code::./CustomHttpServiceArgumentResolver[tag=httpserviceclient,indent=0] A custom argument resolver could be implemented like this: @@ -1021,7 +1021,7 @@ the use of more fine-grained method parameters for individual parts of the reque -[[rest-http-interface-return-values]] +[[rest-http-service-client-return-values]] === Return Values The supported return values depend on the underlying client. @@ -1097,7 +1097,7 @@ underlying HTTP client, which operates at a lower level and provides more contro `InputStream` or `ResponseEntity` that provides access to the raw response body content. -[[rest-http-interface-exceptions]] +[[rest-http-service-client-exceptions]] === Error Handling To customize error handling for HTTP Service client proxies, you can configure the @@ -1134,7 +1134,7 @@ documentation for each client, as well as the Javadoc of `defaultStatusHandler` -[[rest-http-interface-adapter-decorator]] +[[rest-http-service-client-adapter-decorator]] === Decorating the Adapter `HttpExchangeAdapter` and `ReactorHttpExchangeAdapter` are contracts that decouple HTTP @@ -1162,8 +1162,8 @@ built-in decorators to suppress 404 exceptions and return a `ResponseEntity` wit -[[rest-http-interface-group-config]] -=== HTTP Interface Groups +[[rest-http-service-client-group-config]] +=== HTTP Service Groups It's trivial to create client proxies with `HttpServiceProxyFactory`, but to have them declared as beans leads to repetitive configuration. You may also have multiple diff --git a/framework-docs/modules/ROOT/pages/web/webflux-http-interface-client.adoc b/framework-docs/modules/ROOT/pages/web/webflux-http-service-client.adoc similarity index 68% rename from framework-docs/modules/ROOT/pages/web/webflux-http-interface-client.adoc rename to framework-docs/modules/ROOT/pages/web/webflux-http-service-client.adoc index 890478d79bb..55280b4a344 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-http-interface-client.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-http-service-client.adoc @@ -1,9 +1,9 @@ -[[webflux-http-interface-client]] -= HTTP Interface Client +[[webflux-http-service-client]] += HTTP Service 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 xref:integration/rest-clients.adoc#rest-http-interface[REST Endpoints] for details. +See xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service Clients] for details. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc b/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc index 2065a962f1e..070bc7798c7 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc @@ -17,7 +17,7 @@ to annotated controller methods with an API version to functional endpoints with an API version Client support for API versioning is available also in `RestClient`, `WebClient`, and -xref:integration/rest-clients.adoc#rest-http-interface[HTTP Service] clients, as well as +xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service] clients, as well as for testing in `WebTestClient`. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc index 2ddc29f80a8..c385221e306 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc @@ -629,17 +629,16 @@ Kotlin:: == `@HttpExchange` [.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-httpexchange-annotation[See equivalent in the Servlet stack]# -While the main purpose of `@HttpExchange` is to abstract HTTP client code with a -generated proxy, the -xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] on which -such annotations are placed is a contract neutral to client vs server use. -In addition to simplifying client code, there are also cases where an HTTP Interface -may be a convenient way for servers to expose their API for client access. This leads -to increased coupling between client and server and is often not a good choice, -especially for public API's, but may be exactly the goal for an internal API. -It is an approach commonly used in Spring Cloud, and it is why `@HttpExchange` is -supported as an alternative to `@RequestMapping` for server side handling in -controller classes. +While the main purpose of `@HttpExchange` is for an HTTP Service +xref:integration/rest-clients.adoc#rest-http-service-client[client with a generated proxy], +the HTTP Service interface on which such annotations are placed is a contract neutral +to client vs server use. In addition to simplifying client code, there are also cases +where an HTTP Service interface may be a convenient way for servers to expose their +API for client access. This leads to increased coupling between client and server and +is often not a good choice, especially for public API's, but may be exactly the goal +for an internal API. It is an approach commonly used in Spring Cloud, and it is why +`@HttpExchange` is supported as an alternative to `@RequestMapping` for server side +handling in controller classes. For example: @@ -710,5 +709,5 @@ path, and content types. For method parameters and returns values, generally, `@HttpExchange` supports a subset of the method parameters that `@RequestMapping` does. Notably, it excludes any server-side specific parameter types. For details, see the list for -xref:integration/rest-clients.adoc#rest-http-interface-method-parameters[@HttpExchange] and +xref:integration/rest-clients.adoc#rest-http-service-client-method-parameters[@HttpExchange] and xref:web/webflux/controller/ann-methods/arguments.adoc[@RequestMapping]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc index e22a3612021..03b8950d7e4 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc @@ -30,12 +30,12 @@ libraries. See xref:integration/rest-clients.adoc#rest-resttemplate[`RestTemplate`] for details. -[[webmvc-http-interface]] -== HTTP Interface +[[webmvc-http-service-client]] +== HTTP Service Client The Spring Framework 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 choosing an API style such as synchronous or reactive. -See xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] for details. +See xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service Client] for details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc index 4cb7dd94797..6d548ad356b 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc @@ -16,7 +16,7 @@ to annotated controller methods with an API version to functional endpoints with an API version Client support for API versioning is available also in `RestClient`, `WebClient`, and -xref:integration/rest-clients.adoc#rest-http-interface[HTTP Service] clients, as well as +xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service] clients, as well as for testing in MockMvc and `WebTestClient`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc index 1590753e000..77c64535a27 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc @@ -659,10 +659,9 @@ Kotlin:: [.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-httpexchange-annotation[See equivalent in the Reactive stack]# While the main purpose of `@HttpExchange` is to abstract HTTP client code with a -generated proxy, the -xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] on which -such annotations are placed is a contract neutral to client vs server use. -In addition to simplifying client code, there are also cases where an HTTP Interface +generated proxy, the interface on which such annotations are placed is a contract neutral +to client vs server use. In addition to simplifying client code, there are also cases +where an xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service Client] may be a convenient way for servers to expose their API for client access. This leads to increased coupling between client and server and is often not a good choice, especially for public API's, but may be exactly the goal for an internal API. @@ -739,7 +738,7 @@ path, and content types. For method parameters and returns values, generally, `@HttpExchange` supports a subset of the method parameters that `@RequestMapping` does. Notably, it excludes any server-side specific parameter types. For details, see the list for -xref:integration/rest-clients.adoc#rest-http-interface-method-parameters[@HttpExchange] and +xref:integration/rest-clients.adoc#rest-http-service-client-method-parameters[@HttpExchange] and xref:web/webmvc/mvc-controller/ann-methods/arguments.adoc[@RequestMapping]. `@HttpExchange` also supports a `headers()` parameter which accepts `"name=value"`-like diff --git a/framework-docs/src/main/java/org/springframework/docs/integration/resthttpinterface/customresolver/CustomHttpServiceArgumentResolver.java b/framework-docs/src/main/java/org/springframework/docs/integration/resthttpserviceclient/customresolver/CustomHttpServiceArgumentResolver.java similarity index 95% rename from framework-docs/src/main/java/org/springframework/docs/integration/resthttpinterface/customresolver/CustomHttpServiceArgumentResolver.java rename to framework-docs/src/main/java/org/springframework/docs/integration/resthttpserviceclient/customresolver/CustomHttpServiceArgumentResolver.java index 3702dc51048..6982f682d0c 100644 --- a/framework-docs/src/main/java/org/springframework/docs/integration/resthttpinterface/customresolver/CustomHttpServiceArgumentResolver.java +++ b/framework-docs/src/main/java/org/springframework/docs/integration/resthttpserviceclient/customresolver/CustomHttpServiceArgumentResolver.java @@ -14,7 +14,7 @@ * limitations under the License. */ -package org.springframework.docs.integration.resthttpinterface.customresolver; +package org.springframework.docs.integration.resthttpserviceclient.customresolver; import java.util.List; @@ -28,14 +28,14 @@ import org.springframework.web.service.invoker.HttpServiceProxyFactory; public class CustomHttpServiceArgumentResolver { - // tag::httpinterface[] + // tag::httpserviceclient[] public interface RepositoryService { @GetExchange("/repos/search") List searchRepository(Search search); } - // end::httpinterface[] + // end::httpserviceclient[] class Sample { diff --git a/framework-docs/src/main/kotlin/org/springframework/docs/integration/resthttpinterface/customresolver/CustomHttpServiceArgumentResolver.kt b/framework-docs/src/main/kotlin/org/springframework/docs/integration/resthttpserviceclient/customresolver/CustomHttpServiceArgumentResolver.kt similarity index 94% rename from framework-docs/src/main/kotlin/org/springframework/docs/integration/resthttpinterface/customresolver/CustomHttpServiceArgumentResolver.kt rename to framework-docs/src/main/kotlin/org/springframework/docs/integration/resthttpserviceclient/customresolver/CustomHttpServiceArgumentResolver.kt index b1412985d7e..8f608e2d182 100644 --- a/framework-docs/src/main/kotlin/org/springframework/docs/integration/resthttpinterface/customresolver/CustomHttpServiceArgumentResolver.kt +++ b/framework-docs/src/main/kotlin/org/springframework/docs/integration/resthttpserviceclient/customresolver/CustomHttpServiceArgumentResolver.kt @@ -14,7 +14,7 @@ * limitations under the License. */ -package org.springframework.docs.integration.resthttpinterface.customresolver +package org.springframework.docs.integration.resthttpserviceclient.customresolver import org.springframework.core.MethodParameter import org.springframework.web.client.RestClient @@ -26,14 +26,14 @@ import org.springframework.web.service.invoker.HttpServiceProxyFactory class CustomHttpServiceArgumentResolver { - // tag::httpinterface[] + // tag::httpserviceclient[] interface RepositoryService { @GetExchange("/repos/search") fun searchRepository(search: Search): List } - // end::httpinterface[] + // end::httpserviceclient[] class Sample { fun sample() { diff --git a/spring-web/src/main/java/org/springframework/web/service/invoker/HttpRequestValues.java b/spring-web/src/main/java/org/springframework/web/service/invoker/HttpRequestValues.java index d5b20179a24..3e4dcb5a0a5 100644 --- a/spring-web/src/main/java/org/springframework/web/service/invoker/HttpRequestValues.java +++ b/spring-web/src/main/java/org/springframework/web/service/invoker/HttpRequestValues.java @@ -127,7 +127,7 @@ public class HttpRequestValues { /** * Return the {@link UriBuilderFactory} to expand * the {@link HttpRequestValues#uriTemplate} and {@link #getUriVariables()} with. - *

The {@link UriBuilderFactory} is passed into the HTTP interface method + *

The {@link UriBuilderFactory} is passed into the HTTP Service client method * in order to override the UriBuilderFactory (and its baseUrl) used by the * underlying client. * @since 6.1 diff --git a/spring-web/src/main/java/org/springframework/web/service/registry/HttpServiceProxyRegistry.java b/spring-web/src/main/java/org/springframework/web/service/registry/HttpServiceProxyRegistry.java index 77462866391..f6266cf1aa8 100644 --- a/spring-web/src/main/java/org/springframework/web/service/registry/HttpServiceProxyRegistry.java +++ b/spring-web/src/main/java/org/springframework/web/service/registry/HttpServiceProxyRegistry.java @@ -33,7 +33,7 @@ public interface HttpServiceProxyRegistry { * Return an HTTP service client from any group as long as there is only one * client of this type across all groups. * @param httpServiceType the type of client - * @param

the type of HTTP interface client + * @param

the type of HTTP service client * @return the matched client * @throws IllegalArgumentException if there is no client of the given type, * or there is more than one client of the given type. @@ -44,7 +44,7 @@ public interface HttpServiceProxyRegistry { * Return an HTTP service client from the named group. * @param groupName the name of the group * @param httpServiceType the type of client - * @param

the type of HTTP interface client + * @param

the type of HTTP service client * @return the matched client * @throws IllegalArgumentException if there is no matching client. */