Polishing API versioning ref docs
This commit is contained in:
rstoyanchev
parent
785aab8ad5
commit
3cb8a833e4
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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].
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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].
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue