Document HTTP Service client support

Closes gh-47179

Author: philwebb

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/io/rest-client.adoc

@@ -306,3 +306,163 @@ You can also define javadoc:org.springframework.web.client.ApiVersionInserter[]
 
 TIP: API versioning is also supported on the server-side.
 See the xref:web/servlet.adoc#web.servlet.spring-mvc.api-versioning[Spring MVC] and xref:web/reactive.adoc#web.reactive.webflux.api-versioning[Spring WebFlux] sections for details.
+
+
+
+[[io.rest-client.httpservice]]
+== HTTP Service Interface Clients
+
+Instead of directly using a javadoc:org.springframework.web.client.RestClient[] or javadoc:org.springframework.web.reactive.function.client.WebClient[] to call an HTTP service, it's also possible to call them using annotated Java interfaces.
+
+HTTP Service interfaces defines a service contract by using methods that are annotated with javadoc:org.springframework.web.service.annotation.HttpExchange[format=annotation], or more typically the method specific variants (javadoc:org.springframework.web.service.annotation.GetExchange[format=annotation], javadoc:org.springframework.web.service.annotation.PostExchange[format=annotation], javadoc:org.springframework.web.service.annotation.DeleteExchange[format=annotation], etc).
+
+For example, the following code defines an HTTP Service for an an "`echo`" API that will return a JSON object containing an echo of the request.
+
+include-code::EchoService[]
+
+More details about how to develop HTTP Service interface clients can be found in the {url-spring-framework-docs}/integration/rest-clients.html#rest-http-interface[Spring Framework reference documentation].
+
+
+
+[[io.rest-client.httpservice.importing]]
+=== Importing HTTP Services
+
+In order to use an HTTP Service interface as client you need to import it.
+One way to achieve this is to use the javadoc:org.springframework.web.service.registry.ImportHttpServices[format=annotation] annotation, typically on your main application class.
+You can use the annotation to import specific classes, or scan for classes to import from specific packages.
+
+For example, the following configuration will scan for HTTP Service interfaces in the `com.example.myclients` package:
+
+include-code::MyApplication[]
+
+
+
+[[io.rest-client.httpservice.groups]]
+=== Service Client Groups
+
+Hard-coding absolute URLs in javadoc:org.springframework.web.service.annotation.HttpExchange[format=annotation] annotations is often not ideal in production applications.
+Instead, you will typically want to give the HTTP Service client a logical name in your code, and then lookup a URL from a property based on that name.
+
+HTTP Service clients allow you to do this by registering them into named groups.
+An HTTP Service group is a collection of HTTP Service interfaces that all share common features.
+
+For example, we may want to define an "`echo`" group to use for HTTP Service clients that call `\https://echo.zuplo.io`.
+
+NOTE: HTTP Service groups can be used to define more than just URLs.
+For example, your group could define connection timeouts and SSL settings.
+You can also associate client customization logic to a group, such as adding code to insert required authorization headers.
+
+To associate an HTTP Service interface with a group when using javadoc:org.springframework.web.service.registry.ImportHttpServices[format=annotation] you can use the `group` attribute.
+
+For example, if we assume our example above is organized in such a way that all HTTP Service interfaces in the `com.example.myclients` package belong to the `echo` group.
+We first remove the hardcoded URL from the service interface:
+
+include-code::EchoService[]
+
+We can then write:
+
+include-code::MyApplication[]
+
+And finally we can then use a `base-url` property to link the `echo` group to an actual URL.
+
+For a `RestClient` backed HTTP Service client this would be:
+
+[configprops,yaml]
+----
+spring:
+  http:
+    client:
+      service:
+        group:
+          echo:
+            base-url: "https://echo.zuplo.io"
+----
+
+For a `WebClient` backed HTTP Service client, we'd use the reactive variant:
+
+[configprops,yaml]
+----
+spring:
+  http:
+    reactiveclient:
+      service:
+        group:
+          echo:
+            base-url: "https://echo.zuplo.io"
+----
+
+TIP: HTTP Service clients will be associated with a group named "`default`" if you don't specify a group.
+
+[NOTE]
+====
+If you have multiple HTTP Service interfaces in the same package that need to be associated with different groups you can list them individually.
+The javadoc:org.springframework.web.service.registry.ImportHttpServices[format=annotation] is repeatable and the `types` attributes allows you to import individual classes.
+
+For example:
+
+include-code::repeat/MyApplication[]
+====
+
+
+
+[[io.rest-client.httpservice.properties]]
+=== Configuration Properties
+
+Configuration properties for HTTP Services can be specified under `spring.http.client.service` for `RestClient` backed clients and `spring.http.reactiveclient.service` for `WebClient` backed clients.
+
+You can use properties to configure aspects such as:
+
+* The base URL.
+* Any default default headers that should be sent.
+* API versioning configuration.
+* Redirect settings.
+* Connection and read timeouts.
+* SSL bundles to use.
+
+Properties are hierarchical and can be specified per-group, or for all HTTP Service clients.
+Some properties can also be specified as xref:/io/rest-client.adoc#io.rest-client.clienthttprequestfactory.configuration[global client configuration], so that they are considered for both HTTP Service clients and direct use of `RestClient` or `WebClient`.
+
+For example, the properties below will:
+
+* Configure all HTTP Service client and `RestClient` beans to use a one second connect timeout (unless otherwise overridden).
+* Configure all HTTP Service clients to use a two second read timeout (unless otherwise overridden).
+* Configure HTTP Service clients in the "`echo`" group to use a specific base URL.
+
+[configprops,yaml]
+----
+spring:
+  http:
+    client:
+      connect-timeout: 1s
+      service:
+        read-timeout: 2s;
+        group:
+          echo:
+            base-url: "https://echo.zuplo.io"
+----
+
+
+
+[[io.rest-client.httpservice.customization]]
+=== Customization
+
+If you need to customize HTTP Service clients beyond basic properties, you can use an HTTP Service group configurer.
+For `RestClient` backed HTTP Service clients, you can declare a bean that implements javadoc:org.springframework.web.client.support.RestClientHttpServiceGroupConfigurer[].
+For `WebClient` backed HTTP Service clients you can declare a bean that implements javadoc:org.springframework.web.reactive.function.client.support.WebClientHttpServiceGroupConfigurer[].
+
+Both work in the same way and will be automatically applied by Spring Boot's auto-configuraiton.
+
+For example, the following configuration would add a group customizer that adds an HTTP header to each outgoing request containing the group name:
+
+include-code::MyHttpServiceGroupConfiguration[]
+
+
+
+[[io.rest-client.httpservice.advanced-configuration]]
+=== Advanced Configuration
+
+As well as the javadoc:org.springframework.web.service.registry.ImportHttpServices[format=annotation] annotation, Spring Framework also offers an javadoc:org.springframework.web.service.registry.AbstractHttpServiceRegistrar[] class.
+You can javadoc:org.springframework.context.annotation.Import[format=annotation] your own extension of this class to perform programmatic configuration.
+For more details, see {url-spring-framework-docs}/integration/rest-clients.html#rest-http-interface-group-config[Spring Framework's reference documenation].
+
+Regardless of which method you use to register HTTP Service clients, Spring Boot's support remains the same.

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/httpservice/EchoService.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2012-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.io.restclient.httpservice;
+
+import java.util.Map;
+
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.service.annotation.HttpExchange;
+import org.springframework.web.service.annotation.PostExchange;
+
+@HttpExchange(url = "https://echo.zuplo.io")
+public interface EchoService {
+
+	@PostExchange
+	Map<?, ?> echo(@RequestBody Map<String, String> message);
+
+}

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/httpservice/customization/MyHttpServiceGroupConfiguration.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2012-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.io.restclient.httpservice.customization;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.client.support.RestClientHttpServiceGroupConfigurer;
+
+@Configuration(proxyBeanMethods = false)
+public class MyHttpServiceGroupConfiguration {
+
+	@Bean
+	RestClientHttpServiceGroupConfigurer myHttpServiceGroupConfigurer() {
+		return (groups) -> groups.forEachClient((group, clientBuilder) -> {
+			String groupName = group.name();
+			clientBuilder.defaultHeader("service-group", groupName);
+		});
+	}
+
+}

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/httpservice/groups/EchoService.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2012-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.io.restclient.httpservice.groups;
+
+import java.util.Map;
+
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.service.annotation.PostExchange;
+
+public interface EchoService {
+
+	@PostExchange
+	Map<?, ?> echo(@RequestBody Map<String, String> message);
+
+}

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/httpservice/groups/MyApplication.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2012-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.io.restclient.httpservice.groups;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.web.service.registry.ImportHttpServices;
+
+@SpringBootApplication
+@ImportHttpServices(group = "echo", basePackages = "com.example.myclients")
+public class MyApplication {
+
+	public static void main(String[] args) {
+		SpringApplication.run(MyApplication.class, args);
+	}
+
+}

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/httpservice/groups/repeat/EchoService.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2012-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.io.restclient.httpservice.groups.repeat;
+
+import java.util.Map;
+
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.service.annotation.PostExchange;
+
+public interface EchoService {
+
+	@PostExchange("/echo")
+	Map<?, ?> echo(@RequestBody Map<String, String> message);
+
+}

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/httpservice/groups/repeat/MyApplication.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2012-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.io.restclient.httpservice.groups.repeat;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.web.service.registry.ImportHttpServices;
+
+@SpringBootApplication
+@ImportHttpServices(group = "echo", types = EchoService.class)
+@ImportHttpServices(group = "other", types = OtherService.class)
+public class MyApplication {
+
+	public static void main(String[] args) {
+		SpringApplication.run(MyApplication.class, args);
+	}
+
+}

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/httpservice/groups/repeat/OtherService.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2012-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.io.restclient.httpservice.groups.repeat;
+
+import java.util.Map;
+
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.service.annotation.PostExchange;
+
+public interface OtherService {
+
+	@PostExchange("/other")
+	Map<?, ?> other(@RequestBody Map<String, String> message);
+
+}