Improve docs on versioning by path segment

Closes gh-35421

Author: rstoyanchev

framework-docs/modules/ROOT/pages/web/webflux/config.adoc

@@ -718,8 +718,12 @@ alternatively use a custom `ApiVersionResolver`:
 - Path segment
 - Media type parameter
 
-TIP: When using a path segment, consider configuring a shared path prefix externally
-in xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching] options.
+To resolve from a path segment, you need to specify the index of the path segment expected
+to contain the version. The path segment must be declared as a URI variable, e.g.
+"/\{version}", "/api/\{version}", etc. where the actual name is not important.
+As the version is typically at the start of the path, consider configuring it externally
+as a common path prefix for all handlers through the
+xref:web/webflux/config.adoc#webflux-config-path-matching[Path Matching] options.
 
 By default, the version is parsed with `SemanticVersionParser`, but you can also configure
 a custom xref:web/webflux-versioning.adoc#webflux-versioning-parser[ApiVersionParser].

framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/api-version.adoc

@@ -15,8 +15,12 @@ alternatively use a custom `ApiVersionResolver`:
 - Path segment
 - Media type parameter
 
-TIP: When using a path segment, consider configuring a shared path prefix externally
-in xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching] options.
+To resolve from a path segment, you need to specify the index of the path segment expected
+to contain the version. The path segment must be declared as a URI variable, e.g.
+"/\{version}", "/api/\{version}", etc. where the actual name is not important.
+As the version is typically at the start of the path, consider configuring it externally
+as a common path prefix for all handlers through the
+xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching] options.
 
 By default, the version is parsed with `SemanticVersionParser`, but you can also configure
 a custom xref:web/webmvc-versioning.adoc#mvc-versioning-parser[ApiVersionParser].

spring-webflux/src/main/java/org/springframework/web/reactive/config/ApiVersionConfigurer.java

@@ -99,7 +99,7 @@ public ApiVersionConfigurer useMediaTypeParameter(MediaType compatibleMediaType,
 	 * <p>Note that this resolver never returns {@code null}, and therefore
 	 * cannot yield to other resolvers, see {@link org.springframework.web.accept.PathApiVersionResolver}.
 	 * @param index the index of the path segment to check; e.g. for URL's like
-	 * "/{version}/..." use index 0, for "/api/{version}/..." index 1.
+	 * {@code "/{version}/..."} use index 0, for {@code "/api/{version}/..."} index 1.
 	 */
 	public ApiVersionConfigurer usePathSegment(int index) {
 		this.versionResolvers.add(new PathApiVersionResolver(index));

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ApiVersionConfigurer.java

@@ -100,7 +100,7 @@ public ApiVersionConfigurer useMediaTypeParameter(MediaType compatibleMediaType,
 	 * <p>Note that this resolver never returns {@code null}, and therefore
 	 * cannot yield to other resolvers, see {@link PathApiVersionResolver}.
 	 * @param index the index of the path segment to check; e.g. for URL's like
-	 * "/{version}/..." use index 0, for "/api/{version}/..." index 1.
+	 * {@code "/{version}/..."} use index 0, for {@code "/api/{version}/..."} index 1.
 	 */
 	public ApiVersionConfigurer usePathSegment(int index) {
 		this.versionResolvers.add(new PathApiVersionResolver(index));