rstoyanchev
7 months ago
9 changed files with 469 additions and 0 deletions
@ -0,0 +1,80 @@
@@ -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 @@
@@ -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 @@
@@ -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 @@
@@ -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 @@
@@ -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