Add API versioning auto-configuration and properties support

Update `RestClient`, `WebClient`, Spring MVC and Spring WebFlux
auto-configuration to support API versioning.

Closes gh-46519

Author: philwebb

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

@@ -277,3 +277,32 @@ For example, the following will use a JDK client configured with a specific java
 
 include-code::MyClientHttpConfiguration[]
 
+
+
+[[io.rest-client.apiversioning]]
+== API Versioning
+
+Both `WebClient` and `RestClient` support making versioned remote HTTP calls so that APIs can be evolved over time.
+Commonly this involves sending an HTTP header, a query parameter or URL path segment that indicates the version of the API that should be used.
+
+You can configure API versioning using methods on `WebClient.Builder` or `RestClient.Builder`.
+You can also the `spring.http.reactiveclient.webclient.apiversion` or `spring.http.client.restclient.apiversion` properties if you want to apply the same configuration to all builders.
+
+For example, the following adds an `X-Version` HTTP header to all calls from the `RestClient` and uses the version `1.0.0` unless overridden for specific requests:
+
+[configprops,yaml]
+----
+spring:
+  http:
+    client:
+      restclient:
+        apiversion:
+          default: 1.0.0
+          insert:
+            header: X-Version
+----
+
+You can also defined javadoc:org.springframework.web.client.ApiVersionInserter[] and javadoc:org.springframework.web.client.ApiVersionFormatter[] beans if you need more control of the way that version information should be inserted and formatted.
+
+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.

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/web/reactive.adoc

@@ -275,6 +275,38 @@ When it does so, the orders shown in the following table will be used:
 
 
 
+[[web.reactive.webflux.api-versioning]]
+=== API Versioning
+
+Spring WebFlux supports API versioning which can be used to evolve an HTTP API over time.
+The same `@Controller` path can be mapped multiple times to support different versions of the API.
+
+For more details see {url-spring-framework-docs}/web/webflux/controller/ann-requestmapping.html#webflux-ann-requestmapping-version[Spring Framework's reference documentation].
+
+One mappings have been added, you additionally need to configure Spring WebFlux so that it is able to use any version information sent with a request.
+Typically, versions are sent as HTTP headers, query parameters or as part of the path.
+
+To configure Spring WebFlux, you can either use a javadoc:org.springframework.web.reactive.config.WebFluxConfigurer[] bean and override the `configureApiVersioning(...)` method, or you can use properties.
+
+For example, the following will use an `X-Version` HTTP header to obtain version information and default to `1.0.0` when no header is sent.
+
+[configprops,yaml]
+----
+spring:
+  webflux:
+    apiversion:
+      default: 1.0.0
+      use:
+        header: X-Version
+----
+
+For more complete control, you can also define javadoc:org.springframework.web.reactive.accept.ApiVersionResolver[], javadoc:org.springframework.web.reactive.accept.ApiVersionParser[] and javadoc:org.springframework.web.reactive.accept.ApiVersionDeprecationHandler[] beans which will be injected into the auto-configured Spring MVC configuration.
+
+TIP: API versioning is also supported on the client-side with both `WebClient` and `RestClient`.
+See xref:io/rest-client.adoc#io.rest-client.apiversioning[] for details.
+
+
+
 [[web.reactive.reactive-server]]
 == Embedded Reactive Server Support
 

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/web/servlet.adoc

@@ -465,6 +465,38 @@ include-code::MyCorsConfiguration[]
 
 
 
+[[web.servlet.spring-mvc.api-versioning]]
+=== API Versioning
+
+Spring MVC supports API versioning which can be used to evolve an HTTP API over time.
+The same `@Controller` path can be mapped multiple times to support different versions of the API.
+
+For more details see {url-spring-framework-docs}/web/webmvc/mvc-controller/ann-requestmapping.html#mvc-ann-requestmapping-version[Spring Framework's reference documentation].
+
+One mappings have been added, you additionally need to configure Spring MVC so that it is able to use any version information sent with a request.
+Typically, versions are sent as HTTP headers, query parameters or as part of the path.
+
+To configure Spring MVC, you can either use a javadoc:org.springframework.web.servlet.config.annotation.WebMvcConfigurer[] bean and override the `configureApiVersioning(...)` method, or you can use properties.
+
+For example, the following will use an `X-Version` HTTP header to obtain version information and default to `1.0.0` when no header is sent.
+
+[configprops,yaml]
+----
+spring:
+  mvc:
+    apiversion:
+      default: 1.0.0
+      use:
+        header: X-Version
+----
+
+For more complete control, you can also define javadoc:org.springframework.web.accept.ApiVersionResolver[], javadoc:org.springframework.web.accept.ApiVersionParser[] and javadoc:org.springframework.web.accept.ApiVersionDeprecationHandler[] beans which will be injected into the auto-configured Spring MVC configuration.
+
+TIP: API versioning is also supported with both `WebClient` and `RestClient`.
+See xref:io/rest-client.adoc#io.rest-client.apiversioning[] for details.
+
+
+
 [[web.servlet.jersey]]
 == JAX-RS and Jersey
 

module/spring-boot-http-client/src/main/java/org/springframework/boot/http/client/autoconfigure/ApiversionProperties.java

@@ -0,0 +1,98 @@
+/*
+ * 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.http.client.autoconfigure;
+
+import org.springframework.boot.context.properties.ConfigurationPropertiesSource;
+import org.springframework.boot.context.properties.bind.Name;
+
+/**
+ * API Version properties for reactive and blocking HTTP Clients.
+ *
+ * @author Phillip Webb
+ * @since 4.0.0
+ */
+@ConfigurationPropertiesSource
+public class ApiversionProperties {
+
+	/**
+	 * Default version that should be used for each request.
+	 */
+	@Name("default")
+	private String defaultVersion;
+
+	/**
+	 * How version details should be inserted into requests.
+	 */
+	private final Insert insert = new Insert();
+
+	public String getDefaultVersion() {
+		return this.defaultVersion;
+	}
+
+	public void setDefaultVersion(String defaultVersion) {
+		this.defaultVersion = defaultVersion;
+	}
+
+	public Insert getInsert() {
+		return this.insert;
+	}
+
+	@ConfigurationPropertiesSource
+	public static class Insert {
+
+		/**
+		 * Insert the version into a header with the given name.
+		 */
+		private String header;
+
+		/**
+		 * Insert the version into a query parameter with the given name.
+		 */
+		private String queryParameter;
+
+		/**
+		 * Insert the version into a path segment at the given index.
+		 */
+		private Integer pathSegment;
+
+		public String getHeader() {
+			return this.header;
+		}
+
+		public void setHeader(String header) {
+			this.header = header;
+		}
+
+		public String getQueryParameter() {
+			return this.queryParameter;
+		}
+
+		public void setQueryParameter(String queryParameter) {
+			this.queryParameter = queryParameter;
+		}
+
+		public Integer getPathSegment() {
+			return this.pathSegment;
+		}
+
+		public void setPathSegment(Integer pathSegment) {
+			this.pathSegment = pathSegment;
+		}
+
+	}
+
+}

module/spring-boot-http-client/src/main/java/org/springframework/boot/http/client/autoconfigure/PropertiesApiVersionInserter.java

@@ -0,0 +1,127 @@
+/*
+ * 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.http.client.autoconfigure;
+
+import java.net.URI;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.stream.Stream;
+
+import org.springframework.boot.context.properties.PropertyMapper;
+import org.springframework.boot.http.client.autoconfigure.ApiversionProperties.Insert;
+import org.springframework.http.HttpHeaders;
+import org.springframework.web.client.ApiVersionFormatter;
+import org.springframework.web.client.ApiVersionInserter;
+
+/**
+ * {@link ApiVersionInserter} to apply {@link ApiversionProperties}.
+ *
+ * @author Phillip Webb
+ * @since 4.0.0
+ */
+public final class PropertiesApiVersionInserter implements ApiVersionInserter {
+
+	private final List<ApiVersionInserter> inserters;
+
+	private PropertiesApiVersionInserter(List<ApiVersionInserter> inserters) {
+		this.inserters = inserters;
+	}
+
+	@Override
+	public URI insertVersion(Object version, URI uri) {
+		for (ApiVersionInserter delegate : this.inserters) {
+			uri = delegate.insertVersion(version, uri);
+		}
+		return uri;
+	}
+
+	@Override
+	public void insertVersion(Object version, HttpHeaders headers) {
+		for (ApiVersionInserter delegate : this.inserters) {
+			delegate.insertVersion(version, headers);
+		}
+	}
+
+	/**
+	 * Factory method that returns an {@link ApiVersionInserter} to apply the given
+	 * properties and delegate.
+	 * @param apiVersionInserter a delegate {@link ApiVersionInserter} that should also
+	 * apply (may be {@code null})
+	 * @param apiVersionFormatter the version formatter to use or {@code null}
+	 * @param properties the properties that should be applied
+	 * @return an {@link ApiVersionInserter} or {@code null} if no API version should be
+	 * inserted
+	 */
+	public static ApiVersionInserter get(ApiVersionInserter apiVersionInserter, ApiVersionFormatter apiVersionFormatter,
+			ApiversionProperties... properties) {
+		return get(apiVersionInserter, apiVersionFormatter, Arrays.stream(properties));
+	}
+
+	/**
+	 * Factory method that returns an {@link ApiVersionInserter} to apply the given
+	 * properties and delegate.
+	 * @param apiVersionInserter a delegate {@link ApiVersionInserter} that should also
+	 * apply (may be {@code null})
+	 * @param apiVersionFormatter the version formatter to use or {@code null}
+	 * @param propertiesStream the properties that should be applied
+	 * @return an {@link ApiVersionInserter} or {@code null} if no API version should be
+	 * inserted
+	 */
+	public static ApiVersionInserter get(ApiVersionInserter apiVersionInserter, ApiVersionFormatter apiVersionFormatter,
+			Stream<ApiversionProperties> propertiesStream) {
+		List<ApiVersionInserter> inserters = new ArrayList<>();
+		if (apiVersionInserter != null) {
+			inserters.add(apiVersionInserter);
+		}
+		PropertyMapper map = PropertyMapper.get().alwaysApplyingWhenNonNull();
+		propertiesStream.forEach((properties) -> {
+			if (properties != null && properties.getInsert() != null) {
+				Insert insert = properties.getInsert();
+				Counter counter = new Counter();
+				ApiVersionInserter.Builder builder = ApiVersionInserter.builder();
+				map.from(apiVersionFormatter).to(builder::withVersionFormatter);
+				map.from(insert::getHeader).whenHasText().as(counter::counted).to(builder::useHeader);
+				map.from(insert::getQueryParameter).whenHasText().as(counter::counted).to(builder::useQueryParam);
+				map.from(insert::getPathSegment).as(counter::counted).to(builder::usePathSegment);
+				if (!counter.isEmpty()) {
+					inserters.add(builder.build());
+				}
+			}
+		});
+		return (!inserters.isEmpty()) ? new PropertiesApiVersionInserter(inserters) : null;
+	}
+
+	/**
+	 * Internal counter used to track if properties were applied.
+	 */
+	private static final class Counter {
+
+		private boolean empty = true;
+
+		<T> T counted(T value) {
+			this.empty = false;
+			return value;
+		}
+
+		boolean isEmpty() {
+			return this.empty;
+		}
+
+	}
+
+}