diff --git a/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc b/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc index c05bac73c0e..3982f8243d7 100644 --- 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 index f2a75ba8019..d6135ed8e8d 100644 --- 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 index 295a16a264e..724ae75c2d0 100644 --- 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 index 7ea6fad3ecc..8ba890cb94e 100644 --- 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 index 88ffa09a6a1..ab8a97b1731 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 @@ -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 index cfd4cbb2814..97113efc25a 100644 --- 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].