From 3702031f825362221faa46a3c51591cd0de5628b Mon Sep 17 00:00:00 2001 From: rstoyanchev Date: Tue, 9 Sep 2025 16:18:33 +0100 Subject: [PATCH] Improve docs on versioning by path segment Closes gh-35421 --- framework-docs/modules/ROOT/pages/web/webflux/config.adoc | 8 ++++++-- .../ROOT/pages/web/webmvc/mvc-config/api-version.adoc | 8 ++++++-- .../web/reactive/config/ApiVersionConfigurer.java | 2 +- .../servlet/config/annotation/ApiVersionConfigurer.java | 2 +- 4 files changed, 14 insertions(+), 6 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc index 2fdd068f99e..65259c6c18f 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc +++ b/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]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/api-version.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/api-version.adoc index c989de0dcdd..0f221f33a8e 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/api-version.adoc +++ b/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]. diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/config/ApiVersionConfigurer.java b/spring-webflux/src/main/java/org/springframework/web/reactive/config/ApiVersionConfigurer.java index 549120c5857..183d563169e 100644 --- a/spring-webflux/src/main/java/org/springframework/web/reactive/config/ApiVersionConfigurer.java +++ b/spring-webflux/src/main/java/org/springframework/web/reactive/config/ApiVersionConfigurer.java @@ -99,7 +99,7 @@ public class ApiVersionConfigurer { *

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)); diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ApiVersionConfigurer.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ApiVersionConfigurer.java index f3db4095d4a..cbf9d9a4b63 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ApiVersionConfigurer.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ApiVersionConfigurer.java @@ -100,7 +100,7 @@ public class ApiVersionConfigurer { *

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));