Polishing API versioning ref docs

rstoyanchev · rstoyanchev · commit 3cb8a833e46e · 2025-06-25T12:03:35.000+01:00
diff --git a/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc b/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc
@@ -9,13 +9,14 @@ and underlying strategies.
 
 Please, see also related content in:
 
-- Use xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-version[API Versions]
-to map requests to annotated controller methods
-- Configure API versioning in xref:web/webflux/config.adoc#webflux-config-api-version[WebFlux Config]
+- Configure xref:web/webflux/config.adoc#webflux-config-api-version[API versioning]
+in the WebFlux Config
+- xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-version[Map requests]
+to annotated controller methods with an API version
 
-TIP: API versioning is also supported on the client side in `RestClient`, `WebClient`, and
+Client support for API versioning is available also in `RestClient`, `WebClient`, and
 xref:integration/rest-clients.adoc#rest-http-interface[HTTP Service] clients, as well as
-for testing with `WebTestClient`.
+for testing in `WebTestClient`.
 
 
 
@@ -24,14 +25,16 @@ for testing with `WebTestClient`.
 == ApiVersionStrategy
 [.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-strategy[See equivalent in the Servlet stack]#
 
-This strategy holds all application preferences about how to manage versioning.
-It delegates to xref:#webflux-versioning-resolver[ApiVersionResolver] to resolve versions
-from requests, and to xref:#webflux-versioning-parser[ApiVersionParser] to parse raw version
-values into `Comparable<?>`. It also helps to xref:#webflux-versioning-validation[validate]
-request versions.
+This is the central strategy for API versioning that holds all configured preferences
+related to versioning. It does the following:
 
-NOTE: `ApiVersionStrategy` helps to map requests to `@RequestMapping` controller methods,
-and is initialized by the WebFlux config. Typically, applications do not interact directly with it.
+- Resolves versions from the requests via xref:#webflux-versioning-resolver[ApiVersionResolver]
+- Parses raw version values into `Comparable<?>` with xref:#webflux-versioning-parser[ApiVersionParser]
+- xref:#webflux-versioning-validation[Validates] request versions
+
+`ApiVersionStrategy` helps to map requests to `@RequestMapping` controller methods,
+and is initialized by the WebFlux config. Typically, applications do not interact
+directly with it.
 
 
 
@@ -53,7 +56,7 @@ You can also use a custom `ApiVersionResolver`.
 
 This strategy helps to parse raw version values into `Comparable<?>`, which helps to
 compare, sort, and select versions. By default, the built-in `SemanticApiVersionParser`
-parses a version into `major`, `minor`, and `patch` integer values. Minor and patch
+parses a version into `major`, `minor`, and `patWebFluxch` integer values. Minor and patch
 values are set to 0 if not present.
 
 
@@ -65,13 +68,13 @@ values are set to 0 if not present.
 
 If a request version is not supported, `InvalidApiVersionException` is raised resulting
 in a 400 response. By default, the list of supported versions is initialized from declared
-versions in annotated controller mappings. You can add to that list, or set it explicitly
-to a fixed set of versions (i.e. ignoring declared ones) through the MVC config.
+versions in annotated controller mappings, but you can turn that off through a flag in the
+WebFlux config, and use only the versions configured explicitly in the config.
 
-By default, a version is required when API versioning is enabled, but you can turn that
-off in which case the highest available version is used. You can also specify a default
-version. `MissingApiVersionException` is raised resulting in a 400 response when a
-version is required but not present.
+By default, a version is required when API versioning is enabled, and
+`MissingApiVersionException` is raised resulting in a 400 response if not present.
+You can make it optional in which case the most recent version is used.
+You can also specify a default version to use.
 
 
 
diff --git a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc
@@ -725,16 +725,16 @@ Kotlin::
 Alternatively, the version can be resolved from a request parameter, from a path segment,
 or  through a custom `ApiVersionResolver`.
 
-TIP: When resolving from a path segment, consider configuring a path prefix once in
-xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching] options.
+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.
 
 Raw version values are parsed with `SemanticVersionParser` by default, but you can use
 a custom xref:web/webflux-versioning.adoc#webflux-versioning-parser[ApiVersionParser].
 
 "Supported" versions are transparently detected from versions declared in request mappings
-for convenience, but you can also set the list of supported versions explicitly, and
-ignore declared ones. Requests with a version that is not supported are rejected with an
-`InvalidApiVersionException` resulting in a 400 response.
+for convenience, but you can turn that off through a flag in the WebFlux config, and use only
+the versions configured explicitly in the config. Requests with a version that is not
+supported are rejected with `InvalidApiVersionException` resulting in a 400 response.
 
 Once API versioning is configured, you can begin to map requests to
 xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-version[controller methods]
diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc
@@ -412,24 +412,24 @@ Kotlin::
 == API Version
 [.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-version[See equivalent in the Servlet stack]#
 
-There is no standard way to specify an API version, so you need to configure that first
-through the xref:web/webflux/config.adoc#webflux-config-api-version[WebFlux Config] along with other
-config options. This results in the creation of an
-xref:web/webflux-versioning.adoc#webflux-versioning-strategy[ApiVersionStrategy] that in
-supports request mapping.
+There is no standard way to specify an API version, so when you enable API versioning
+in the xref:web/webflux/config.adoc#webflux-config-api-version[WebFlux Config] you need
+to specify how to resolve the version. The WebFlux Config creates an
+xref:web/webflux-versioning.adoc#webflux-versioning-strategy[ApiVersionStrategy] that in turn
+is used to map requests.
 
 Once API versioning is enabled, you can begin to map requests with versions.
-The `@RequestMapping` version attribute supports the following:
+The `@RequestMapping` `version` attribute supports the following:
 
-- No value -- match any version
-- Fixed version ("1.2") -- match the given version only
-- Baseline version ("1.2+") -- match the given version and above
+- No value -- matches any version
+- Fixed version ("1.2") -- matches the given version only
+- Baseline version ("1.2+") -- matches the given version and above
 
 If multiple controller methods have a version less than or equal to the request version,
-the one closest to the request version is considered for mapping purposes,
+the highest of those, and closest to the request version, is the one considered,
 in effect superseding the rest.
 
-To illustrate this, consider the following controller mappings:
+To illustrate this, consider the following mappings:
 
 [tabs]
 ======
@@ -479,11 +479,12 @@ For request with version `"1.5"`:
 - (4) matches and is *chosen* as the highest match
 
 A request with version `"1.6"` does not have a match. (1) and (3) do match, but are
-superseded by (4), which does not match. In this scenario, `NotAcceptableApiVersionException`
-is raised resulting in a 400 response.
+superseded by (4), which allows only a strict match, and therefore does not match.
+In this scenario, a `NotAcceptableApiVersionException` results in a 400 response.
 
-NOTE: The above assumes the request version is a "supported" versions. If not it would
-fail xref:web/webflux-versioning.adoc#webflux-versioning-validation[Validation].
+NOTE: The above assumes the request version is a
+xref:web/webmvc/mvc-config/api-version.adoc["supported" version], or otherwise it
+would fail xref:web/webflux-versioning.adoc#webflux-versioning-validation[Validation].
 
 
 
diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc
@@ -9,13 +9,13 @@ and underlying strategies.
 
 Please, see also related content in:
 
-- Use xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-version[API Version]
-to map requests to annotated controller methods
-- Configure API versioning in xref:web/webmvc/mvc-config/api-version.adoc[MVC Config]
+- Configure xref:web/webmvc/mvc-config/api-version.adoc[API versioning] in the MVC Config
+- xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-version[Map requests]
+to annotated controller methods with an API version
 
-TIP: API versioning is also supported on the client side in `RestClient`, `WebClient`, and
+Client support for API versioning is available also in `RestClient`, `WebClient`, and
 xref:integration/rest-clients.adoc#rest-http-interface[HTTP Service] clients, as well as
-for testing with `WebTestClient`.
+for testing in MockMvc and `WebTestClient`.
 
 
 
@@ -24,14 +24,16 @@ for testing with `WebTestClient`.
 == ApiVersionStrategy
 [.small]#xref:web/webflux-versioning.adoc#webflux-versioning-strategy[See equivalent in the Reactive stack]#
 
-This strategy holds all application preferences about how to manage versioning.
-It delegates to xref:#mvc-versioning-resolver[ApiVersionResolver] to resolve versions
-from requests, and to xref:#mvc-versioning-parser[ApiVersionParser] to parse raw version
-values into `Comparable<?>`. It also helps to xref:#mvc-versioning-validation[validate]
-request versions.
+This is the central strategy for API versioning that holds all configured preferences
+related to versioning. It does the following:
 
-NOTE: `ApiVersionStrategy` helps to map requests to `@RequestMapping` controller methods,
-and is initialized by the MVC config. Typically, applications do not interact directly with it.
+- Resolves versions from the requests via xref:#mvc-versioning-resolver[ApiVersionResolver]
+- Parses raw version values into `Comparable<?>` with an xref:#mvc-versioning-parser[ApiVersionParser]
+- xref:#mvc-versioning-validation[Validates] request versions
+
+`ApiVersionStrategy` helps to map requests to `@RequestMapping` controller methods,
+and is initialized by the MVC config. Typically, applications do not interact
+directly with it.
 
 
 
@@ -65,13 +67,13 @@ values are set to 0 if not present.
 
 If a request version is not supported, `InvalidApiVersionException` is raised resulting
 in a 400 response. By default, the list of supported versions is initialized from declared
-versions in annotated controller mappings. You can add to that list, or set it explicitly
-to a fixed set of versions (i.e. ignoring declared ones) through the MVC config.
+versions in annotated controller mappings, but you can turn that off through a flag in the
+MVC config, and use only the versions configured explicitly in the config.
 
-By default, a version is required when API versioning is enabled, but you can turn that
-off in which case the highest available version is used. You can also specify a default
-version. `MissingApiVersionException` is raised resulting in a 400 response when a
-version is required but not present.
+By default, a version is required when API versioning is enabled, and
+`MissingApiVersionException` is raised resulting in a 400 response if not present.
+You can make it optional in which case the most recent version is used.
+You can also specify a default version to use.
 
 
 
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
@@ -10,16 +10,16 @@ include-code::./WebConfiguration[tag=snippet,indent=0]
 Alternatively, the version can be resolved from a request parameter, from a path segment,
 or  through a custom `ApiVersionResolver`.
 
-TIP: When resolving from a path segment, consider configuring a path prefix once in
-xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching] options.
+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.
 
 Raw version values are parsed with `SemanticVersionParser` by default, but you can use
 a custom xref:web/webmvc-versioning.adoc#mvc-versioning-parser[ApiVersionParser].
 
 "Supported" versions are transparently detected from versions declared in request mappings
-for convenience, but you can also set the list of supported versions explicitly, and
-ignore declared ones. Requests with a version that is not supported are rejected with an
-`InvalidApiVersionException` resulting in a 400 response.
+for convenience, but you can turn that off through a flag in the MVC config, and use only
+the versions configured explicitly in the config. Requests with a version that is not
+supported are rejected with `InvalidApiVersionException` resulting in a 400 response.
 
 Once API versioning is configured, you can begin to map requests to
 xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-version[controller methods]
diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc
@@ -433,24 +433,24 @@ instead.
 == API Version
 [.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-version[See equivalent in the Reactive stack]#
 
-There is no standard way to specify an API version, so you need to configure that first
-through the xref:web/webmvc/mvc-config/api-version.adoc[MVC Config] along with other
-config options. This results in the creation of an
+There is no standard way to specify an API version, so when you enable API versioning
+in the xref:web/webmvc/mvc-config/api-version.adoc[MVC Config] you need
+to specify how to resolve the version. The MVC Config creates an
 xref:web/webmvc-versioning.adoc#mvc-versioning-strategy[ApiVersionStrategy] that in turn
-supports request mapping.
+is used to map requests.
 
 Once API versioning is enabled, you can begin to map requests with versions.
-The `@RequestMapping` version attribute supports the following:
+The `@RequestMapping` `version` attribute supports the following:
 
-- No value -- match any version
-- Fixed version ("1.2") -- match the given version only
-- Baseline version ("1.2+") -- match the given version and above
+- No value -- matches any version
+- Fixed version ("1.2") -- matches the given version only
+- Baseline version ("1.2+") -- matches the given version and above
 
 If multiple controller methods have a version less than or equal to the request version,
-the one closest to the request version is considered for mapping purposes,
+the highest of those, and closest to the request version, is the one considered,
 in effect superseding the rest.
 
-To illustrate this, consider the following controller mappings:
+To illustrate this, consider the following mappings:
 
 [tabs]
 ======
@@ -500,11 +500,12 @@ For request with version `"1.5"`:
 - (4) matches and is *chosen* as the highest match
 
 A request with version `"1.6"` does not have a match. (1) and (3) do match, but are
-superseded by (4), which does not match. In this scenario, `NotAcceptableApiVersionException`
-is raised resulting in a 400 response.
+superseded by (4), which allows only a strict match, and therefore does not match.
+In this scenario, a `NotAcceptableApiVersionException` results in a 400 response.
 
-NOTE: The above assumes the request version is a "supported" versions. If not it would
-fail xref:web/webmvc-versioning.adoc#mvc-versioning-validation[Validation].
+NOTE: The above assumes the request version is a
+xref:web/webmvc/mvc-config/api-version.adoc["supported" version], or otherwise it
+would fail xref:web/webmvc-versioning.adoc#mvc-versioning-validation[Validation].
 
 
 
