Improve Javadoc for use of ApiVersionInserter

Closes gh-35565

Author: rstoyanchev

spring-test/src/main/java/org/springframework/test/web/reactive/server/WebTestClient.java

@@ -447,6 +447,9 @@ interface Builder {
 		 * Configure an {@link ApiVersionInserter} to abstract how an API version
 		 * specified via {@link RequestHeadersSpec#apiVersion(Object)}
 		 * is inserted into the request.
+		 * <p>{@code ApiVersionInserter} exposes shortcut methods for several
+		 * built-in inserter implementation types. See the class-level Javadoc
+		 * of {@link ApiVersionInserter} for a list of choices.
 		 * @param apiVersionInserter the inserter to use
 		 * @since 7.0
 		 */

spring-test/src/main/java/org/springframework/test/web/servlet/client/RestTestClient.java

@@ -263,6 +263,9 @@ interface Builder<B extends Builder<B>> {
 		 * Configure an {@link ApiVersionInserter} to abstract how an API version
 		 * specified via {@link RequestHeadersSpec#apiVersion(Object)}
 		 * is inserted into the request.
+		 * <p>{@code ApiVersionInserter} exposes shortcut methods for several
+		 * built-in inserter implementation types. See the class-level Javadoc
+		 * of {@link ApiVersionInserter} for a list of choices.
 		 * @param apiVersionInserter the inserter to use
 		 */
 		<T extends B> T apiVersionInserter(ApiVersionInserter apiVersionInserter);

spring-test/src/main/java/org/springframework/test/web/servlet/request/AbstractMockHttpServletRequestBuilder.java

@@ -496,6 +496,9 @@ public B apiVersion(Object version) {
 	 * An inserter may typically be set once (more centrally) via
 	 * {@link org.springframework.test.web.servlet.setup.ConfigurableMockMvcBuilder#defaultRequest(RequestBuilder)}, or
 	 * {@link org.springframework.test.web.servlet.setup.ConfigurableMockMvcBuilder#apiVersionInserter(ApiVersionInserter)}.
+	 * <p>{@code ApiVersionInserter} exposes shortcut methods for several
+	 * built-in inserter implementation types. See the class-level Javadoc
+	 * of {@link ApiVersionInserter} for a list of choices.
 	 * @param versionInserter the inserter to use
 	 * @since 7.0
 	 */

spring-test/src/main/java/org/springframework/test/web/servlet/setup/ConfigurableMockMvcBuilder.java

@@ -80,6 +80,9 @@ <T extends B> T addFilter(
 	/**
 	 * Set the {@link ApiVersionInserter} to use to apply to versions specified via
 	 * {@link org.springframework.test.web.servlet.request.AbstractMockHttpServletRequestBuilder#apiVersion(Object)}.
+	 * <p>{@code ApiVersionInserter} exposes shortcut methods for several
+	 * built-in inserter implementation types. See the class-level Javadoc
+	 * of {@link ApiVersionInserter} for a list of choices.
 	 * @param versionInserter the inserter to use
 	 * @since 7.0
 	 */

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

@@ -23,8 +23,19 @@
 import org.springframework.http.HttpHeaders;
 
 /**
- * Contract to determine how to insert an API version into the URI or headers
- * of a request.
+ * Contract to insert an API version into the URI or headers of a request.
+ *
+ * <p>Use shortcut, static factory methods on this interface to create one of
+ * the built-in inserter type implementations:
+ * <ul>
+ * <li>{@link #useHeader(String)}
+ * <li>{@link #useQueryParam(String)}
+ * <li>{@link #useMediaTypeParam(String)}
+ * <li>{@link #usePathSegment(Integer)}
+ * </ul>
+ *
+ * <p>Use the {@link #builder()} for further options such as if you want to also
+ * configure an {@link ApiVersionFormatter}.
  *
  * @author Rossen Stoyanchev
  * @since 7.0

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

@@ -347,6 +347,9 @@ interface Builder {
 		 * Configure an {@link ApiVersionInserter} to abstract how an API version
 		 * specified via {@link RequestHeadersSpec#apiVersion(Object)}
 		 * is inserted into the request.
+		 * <p>{@code ApiVersionInserter} exposes shortcut methods for several
+		 * built-in inserter implementation types. See the class-level Javadoc
+		 * of {@link ApiVersionInserter} for a list of choices.
 		 * @param apiVersionInserter the inserter to use
 		 * @since 7.0
 		 */

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java

@@ -265,6 +265,9 @@ interface Builder {
 		 * Configure an {@link ApiVersionInserter} to abstract how an API version
 		 * specified via {@link RequestHeadersSpec#apiVersion(Object)}
 		 * is inserted into the request.
+		 * <p>{@code ApiVersionInserter} exposes shortcut methods for several
+		 * built-in inserter implementation types. See the class-level Javadoc
+		 * of {@link ApiVersionInserter} for a list of choices.
 		 * @param apiVersionInserter the inserter to use
 		 * @since 7.0
 		 */