rstoyanchev
7 months ago
9 changed files with 469 additions and 0 deletions
@ -0,0 +1,80 @@ |
|||||||
|
[[webflux-versioning]] |
||||||
|
= API Versioning |
||||||
|
:page-section-summary-toc: 1 |
||||||
|
|
||||||
|
[.small]#xref:web/webmvc-versioning.adoc[See equivalent in the Servlet stack]# |
||||||
|
|
||||||
|
Spring WebFlux supports API versioning. This section provides an overview of the support |
||||||
|
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] |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-versioning-strategy]] |
||||||
|
== 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. |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-versioning-resolver]] |
||||||
|
== ApiVersionResolver |
||||||
|
[.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-resolver[See equivalent in the Servlet stack]# |
||||||
|
|
||||||
|
This strategy resolves the API version from a request. The WebFlux config provides built-in |
||||||
|
options to resolve from a header, a request parameter, or from the URL path. |
||||||
|
You can also use a custom `ApiVersionResolver`. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-versioning-parser]] |
||||||
|
== ApiVersionParser |
||||||
|
[.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-parser[See equivalent in the Servlet stack]# |
||||||
|
|
||||||
|
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 |
||||||
|
values are set to 0 if not present. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-versioning-validation]] |
||||||
|
== Validation |
||||||
|
[.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-validation[See equivalent in the Servlet stack]# |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-versioning-mapping]] |
||||||
|
== Request Mapping |
||||||
|
[.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-mapping[See equivalent in the Servlet stack]# |
||||||
|
|
||||||
|
`ApiVersionStrategy` supports the mapping of requests to annotated controller methods. |
||||||
|
See xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-version[API Versions] |
||||||
|
for more details. |
||||||
@ -0,0 +1,81 @@ |
|||||||
|
[[mvc-versioning]] |
||||||
|
= API Versioning |
||||||
|
:page-section-summary-toc: 1 |
||||||
|
|
||||||
|
[.small]#xref:web/webflux-versioning.adoc[See equivalent in the Reactive stack]# |
||||||
|
|
||||||
|
Spring MVC supports API versioning. This section provides an overview of the support |
||||||
|
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] |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[mvc-versioning-strategy]] |
||||||
|
== 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. |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[mvc-versioning-resolver]] |
||||||
|
== ApiVersionResolver |
||||||
|
[.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-resolver[See equivalent in the Reactive stack]# |
||||||
|
|
||||||
|
This strategy resolves the API version from a request. The MVC config provides built-in |
||||||
|
options to resolve from a header, from a request parameter, or from the URL path. |
||||||
|
You can also use a custom `ApiVersionResolver`. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[mvc-versioning-parser]] |
||||||
|
== ApiVersionParser |
||||||
|
[.small]#xref:web/webflux-versioning.adoc#webflux-versioning-parser[See equivalent in the Reactive stack]# |
||||||
|
|
||||||
|
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 |
||||||
|
values are set to 0 if not present. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[mvc-versioning-validation]] |
||||||
|
== Validation |
||||||
|
[.small]#xref:web/webflux-versioning.adoc#webflux-versioning-validation[See equivalent in the Reactive stack]# |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[mvc-versioning-mapping]] |
||||||
|
== Request Mapping |
||||||
|
[.small]#xref:web/webflux-versioning.adoc#webflux-versioning-mapping[See equivalent in the Reactive stack]# |
||||||
|
|
||||||
|
`ApiVersionStrategy` supports the mapping of requests to annotated controller methods. |
||||||
|
See xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-version[API Version] |
||||||
|
for more details. |
||||||
@ -0,0 +1,26 @@ |
|||||||
|
[[mvc-config-api-version]] |
||||||
|
= API Version |
||||||
|
|
||||||
|
[.small]#xref:web/webflux/config.adoc#webflux-config-api-version[See equivalent in the Reactive stack]# |
||||||
|
|
||||||
|
To enable API versioning with a request header, use the following: |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
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] |
||||||
|
according to the request version. |
||||||
@ -0,0 +1,32 @@ |
|||||||
|
/* |
||||||
|
* Copyright 2002-2024 the original author or authors. |
||||||
|
* |
||||||
|
* Licensed under the Apache License, Version 2.0 (the "License"); |
||||||
|
* you may not use this file except in compliance with the License. |
||||||
|
* You may obtain a copy of the License at |
||||||
|
* |
||||||
|
* https://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
* |
||||||
|
* Unless required by applicable law or agreed to in writing, software |
||||||
|
* distributed under the License is distributed on an "AS IS" BASIS, |
||||||
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
||||||
|
* See the License for the specific language governing permissions and |
||||||
|
* limitations under the License. |
||||||
|
*/ |
||||||
|
|
||||||
|
package org.springframework.docs.web.webmvc.mvcconfig.mvcconfigapiversion; |
||||||
|
|
||||||
|
import org.springframework.context.annotation.Configuration; |
||||||
|
import org.springframework.web.servlet.config.annotation.ApiVersionConfigurer; |
||||||
|
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; |
||||||
|
|
||||||
|
// tag::snippet[]
|
||||||
|
@Configuration |
||||||
|
public class WebConfiguration implements WebMvcConfigurer { |
||||||
|
|
||||||
|
@Override |
||||||
|
public void configureApiVersioning(ApiVersionConfigurer configurer) { |
||||||
|
configurer.useRequestHeader("X-API-Version"); |
||||||
|
} |
||||||
|
} |
||||||
|
// end::snippet[]
|
||||||
@ -0,0 +1,31 @@ |
|||||||
|
/* |
||||||
|
* Copyright 2002-2024 the original author or authors. |
||||||
|
* |
||||||
|
* Licensed under the Apache License, Version 2.0 (the "License"); |
||||||
|
* you may not use this file except in compliance with the License. |
||||||
|
* You may obtain a copy of the License at |
||||||
|
* |
||||||
|
* https://www.apache.org/licenses/LICENSE-2.0 |
||||||
|
* |
||||||
|
* Unless required by applicable law or agreed to in writing, software |
||||||
|
* distributed under the License is distributed on an "AS IS" BASIS, |
||||||
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
||||||
|
* See the License for the specific language governing permissions and |
||||||
|
* limitations under the License. |
||||||
|
*/ |
||||||
|
|
||||||
|
package org.springframework.docs.web.webmvc.mvcconfig.mvcconfigapiversion |
||||||
|
|
||||||
|
import org.springframework.context.annotation.Configuration |
||||||
|
import org.springframework.web.servlet.config.annotation.ApiVersionConfigurer |
||||||
|
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer |
||||||
|
|
||||||
|
// tag::snippet[] |
||||||
|
@Configuration |
||||||
|
class WebConfiguration : WebMvcConfigurer { |
||||||
|
|
||||||
|
override fun configureApiVersioning(configurer: ApiVersionConfigurer) { |
||||||
|
configurer.useRequestHeader("X-API-Version") |
||||||
|
} |
||||||
|
} |
||||||
|
// end::snippet[] |
||||||
Loading…
Reference in new issue