root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Add docs for API version deprecation support 

Closes gh-35049
This commit is contained in:
rstoyanchev 2025-06-25 12:03:22 +01:00
parent 482cfb0b18
commit 40eb9c2c81
6 changed files with 96 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc
View File

@ -79,6 +79,20 @@ You can also specify a default version to use.
[[webflux-versioning-deprecation-handler]]
== ApiVersionDeprecationHandler
[.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-deprecation-handler[See equivalent in the Reactive stack]#
This strategy can be configured to send hints and information about deprecated versions to
clients via response headers. The built-in `StandardApiVersionDeprecationHandler`
can set the "Deprecation" "Sunset" headers and "Link" headers as defined in
https://datatracker.ietf.org/doc/html/rfc9745[RFC 9745] and
https://datatracker.ietf.org/doc/html/rfc8594[RFC 8594]. You can also configure a custom
handler for different headers.
[[webflux-versioning-mapping]]
== Request Mapping
[.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-mapping[See equivalent in the Servlet stack]#

27
framework-docs/modules/ROOT/pages/web/webflux/config.adoc
View File

@ -690,7 +690,7 @@ reliance on it.
== API Version
[.small]#xref:web/webmvc/mvc-config/api-version.adoc[See equivalent in the Servlet stack]#
To enable API versioning with a request header, use the following:
To enable API versioning, use the `ApiVersionConfigurer` callback of `WebFluxConfigurer`:
[tabs]
======
@ -722,19 +722,30 @@ Kotlin::
----
======
Alternatively, the version can be resolved from a request parameter, from a path segment,
or through a custom `ApiVersionResolver`.
You can resolve the version through one of the built-in options listed below, or
alternatively use a custom `ApiVersionResolver`:
- Request header
- Request parameter
- Path segment
- Media type parameter
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
By default, the version is parsed with `SemanticVersionParser`, but you can also configure
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 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.
Supported versions are transparently detected from versions declared in request mappings
for convenience, but you can turn that off through a flag in the WebFlux config, and
consider only the versions configured explicitly in the config as supported.
Requests with a version that is not supported are rejected with
`InvalidApiVersionException` resulting in a 400 response.
You can set an `ApiVersionDeprecationHandler` to send information about deprecated
versions to clients. The built-in standard handler can set "Deprecation", "Sunset", and
"Link" headers based on https://datatracker.ietf.org/doc/html/rfc9745[RFC 9745] and
https://datatracker.ietf.org/doc/html/rfc8594[RFC 8594].
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]

17
framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc
View File

@ -30,6 +30,7 @@ related to versioning. It does the following:
- 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
- Sends deprecation hints in the responses
`ApiVersionStrategy` helps to map requests to `@RequestMapping` controller methods,
and is initialized by the MVC config. Typically, applications do not interact
@ -40,7 +41,7 @@ directly with it.
[[mvc-versioning-resolver]]
== ApiVersionResolver
[.small]#xref:web/webmvc-versioning.adoc#mvc-versioning-resolver[See equivalent in the Reactive stack]#
[.small]#xref:web/webflux-versioning.adoc#webflux-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.
@ -78,6 +79,20 @@ You can also specify a default version to use.
[[mvc-versioning-deprecation-handler]]
== ApiVersionDeprecationHandler
[.small]#xref:web/webflux-versioning.adoc#webflux-versioning-deprecation-handler[See equivalent in the Reactive stack]#
This strategy can be configured to send hints and information about deprecated versions to
clients via response headers. The built-in `StandardApiVersionDeprecationHandler`
can set the "Deprecation" "Sunset" headers and "Link" headers as defined in
https://datatracker.ietf.org/doc/html/rfc9745[RFC 9745] and
https://datatracker.ietf.org/doc/html/rfc8594[RFC 8594]. You can also configure a custom
handler for different headers.
[[mvc-versioning-mapping]]
== Request Mapping
[.small]#xref:web/webflux-versioning.adoc#webflux-versioning-mapping[See equivalent in the Reactive stack]#

27
framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/api-version.adoc
View File

@ -3,23 +3,34 @@
[.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:
To enable API versioning, use the `ApiVersionConfigurer` callback of `WebMvcConfigurer`:
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`.
You can resolve the version through one of the built-in options listed below, or
alternatively use a custom `ApiVersionResolver`:
- Request header
- Request parameter
- Path segment
- Media type parameter
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
By default, the version is parsed with `SemanticVersionParser`, but you can also configure
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 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.
Supported versions are transparently detected from versions declared in request mappings
for convenience, but you can turn that off through a flag in the MVC config, and
consider only the versions configured explicitly in the config as supported.
Requests with a version that is not supported are rejected with
`InvalidApiVersionException` resulting in a 400 response.
You can set an `ApiVersionDeprecationHandler` to send information about deprecated
versions to clients. The built-in standard handler can set "Deprecation", "Sunset", and
"Link" headers based on https://datatracker.ietf.org/doc/html/rfc9745[RFC 9745] and
https://datatracker.ietf.org/doc/html/rfc8594[RFC 8594].
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]

28
spring-webflux/src/main/java/org/springframework/web/reactive/config/ApiVersionConfigurer.java
View File

@ -53,12 +53,12 @@ public class ApiVersionConfigurer {
private @Nullable String defaultVersion;
private @Nullable ApiVersionDeprecationHandler deprecationHandler;
private final Set<String> supportedVersions = new LinkedHashSet<>();
private boolean detectSupportedVersions = true;
private @Nullable ApiVersionDeprecationHandler deprecationHandler;
/**
* Add a resolver that extracts the API version from a request header.
@ -145,18 +145,6 @@ public class ApiVersionConfigurer {
return this;
}
/**
* Configure a handler to add handling for requests with a deprecated API
* version. Typically, this involves sending hints and information about
* the deprecation in response headers.
* @param handler the handler to use
* @see StandardApiVersionDeprecationHandler
*/
public ApiVersionConfigurer setDeprecationHandler(ApiVersionDeprecationHandler handler) {
this.deprecationHandler = handler;
return this;
}
/**
* Add to the list of supported versions to check against before raising
* {@link InvalidApiVersionException} for unknown versions.
@ -187,6 +175,18 @@ public class ApiVersionConfigurer {
return this;
}
/**
* Configure a handler to add handling for requests with a deprecated API
* version. Typically, this involves sending hints and information about
* the deprecation in response headers.
* @param handler the handler to use
* @see StandardApiVersionDeprecationHandler
*/
public ApiVersionConfigurer setDeprecationHandler(ApiVersionDeprecationHandler handler) {
this.deprecationHandler = handler;
return this;
}
protected @Nullable ApiVersionStrategy getApiVersionStrategy() {
if (this.versionResolvers.isEmpty()) {
return null;

28
spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ApiVersionConfigurer.java
View File

@ -53,12 +53,12 @@ public class ApiVersionConfigurer {
private @Nullable String defaultVersion;
private @Nullable ApiVersionDeprecationHandler deprecationHandler;
private final Set<String> supportedVersions = new LinkedHashSet<>();
private boolean detectSupportedVersions = true;
private @Nullable ApiVersionDeprecationHandler deprecationHandler;
/**
* Add resolver to extract the version from a request header.
@ -145,18 +145,6 @@ public class ApiVersionConfigurer {
return this;
}
/**
* Configure a handler to add handling for requests with a deprecated API
* version. Typically, this involves sending hints and information about
* the deprecation in response headers.
* @param handler the handler to use
* @see StandardApiVersionDeprecationHandler
*/
public ApiVersionConfigurer setDeprecationHandler(ApiVersionDeprecationHandler handler) {
this.deprecationHandler = handler;
return this;
}
/**
* Add to the list of supported versions to check against before raising
* {@link InvalidApiVersionException} for unknown versions.
@ -187,6 +175,18 @@ public class ApiVersionConfigurer {
return this;
}
/**
* Configure a handler to add handling for requests with a deprecated API
* version. Typically, this involves sending hints and information about
* the deprecation in response headers.
* @param handler the handler to use
* @see StandardApiVersionDeprecationHandler
*/
public ApiVersionConfigurer setDeprecationHandler(ApiVersionDeprecationHandler handler) {
this.deprecationHandler = handler;
return this;
}
protected @Nullable ApiVersionStrategy getApiVersionStrategy() {
if (this.versionResolvers.isEmpty()) {
return null;