Update router function docs for API versioning

Closes gh-35113
2026-09-17 16:39:29 +00:00 · 2025-07-02 15:09:32 +01:00
parent 701e034c0e
commit 26d413c521
6 changed files with 111 additions and 11 deletions
@@ -585,10 +585,10 @@ parameter, though which additional constraints can be expressed.
 === Predicates

 You can write your own `RequestPredicate`, but the `RequestPredicates` utility class
-offers commonly used implementations, based on the request path, HTTP method, content-type,
-and so on.
-The following example uses a request predicate to create a constraint based on the `Accept`
-header:
+offers built-in options for common needs for matching based on the HTTP method, request
+path, headers, xref:#api-version[API version], and more.
+
+The following example uses an `Accept` header, request predicate:

 [tabs]
 ======
@@ -783,6 +783,51 @@ Kotlin::
 ======


+
+[[api-version]]
+=== API Version
+
+Router functions support matching by API version.
+
+First, enable API versioning in the
+xref:web/webflux/config.adoc#webflux-config-api-version[WebFlux Config], and then you can
+use the `version` xref:#webflux-fn-predicates[predicate] as follows:
+
+[tabs]
+======
+Java::
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	RouterFunction<ServerResponse> route = RouterFunctions.route()
+		.GET("/hello-world", version("1.2"),
+			request -> ServerResponse.ok().body("Hello World")).build();
+----
+
+Kotlin::
+
+[source,kotlin,indent=0,subs="verbatim,quotes"]
+----
+	val route = coRouter {
+		GET("/hello-world", version("1.2")) {
+			ServerResponse.ok().bodyValueAndAwait("Hello World")
+		}
+	}
+----
+======
+
+The `version` predicate can be:
+
+- Fixed version ("1.2") -- matches the given version only
+- Baseline version ("1.2+") -- matches the given version and above, up to the highest
+xref:web/webmvc/mvc-config/api-version.adoc[supported version].
+
+See xref:web/webflux-versioning.adoc[API Versioning] for more details on underlying
+infrastructure and support for API Versioning.
+
+
+
+
 [[webflux-fn-serving-resources]]
 == Serving Resources

@@ -13,6 +13,8 @@ Please, see also related content in:
 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
+- xref:web/webflux-functional.adoc#api-version[Route requests]
+to functional endpoints with an API version

 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
@@ -483,8 +483,12 @@ superseded by (4), which allows only a strict match, and therefore does not matc
 In this scenario, a `NotAcceptableApiVersionException` results in a 400 response.

 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].
+xref:web/webflux/config.adoc#webflux-config-api-version["supported" version],
+or otherwise it would fail.
+
+See xref:web/webflux-versioning.adoc[API Versioning] for more details on underlying
+infrastructure and support for API Versioning.
+



@@ -555,10 +555,10 @@ parameter, through which additional constraints can be expressed.
 === Predicates

 You can write your own `RequestPredicate`, but the `RequestPredicates` utility class
-offers commonly used implementations, based on the request path, HTTP method, content-type,
-and so on.
-The following example uses a request predicate to create a constraint based on the `Accept`
-header:
+offers built-in options for common needs for matching based on the HTTP method, request
+path, headers, xref:#api-version[API version], and more.
+
+The following example uses an `Accept` header, request predicate:

 [tabs]
 ======
@@ -761,6 +761,51 @@ Kotlin::
 ======


+
+[[api-version]]
+=== API Version
+
+Router functions support matching by API version.
+
+First, enable API versioning in the
+xref:web/webmvc/mvc-config/api-version.adoc[MVC Config], and then you can use the
+`version` xref:#webmvc-fn-predicates[predicate] as follows:
+
+[tabs]
+======
+Java::
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	RouterFunction<ServerResponse> route = RouterFunctions.route()
+		.GET("/hello-world", version("1.2"),
+			request -> ServerResponse.ok().body("Hello World")).build();
+----
+
+Kotlin::
+
+[source,kotlin,indent=0,subs="verbatim,quotes"]
+----
+	val route = router {
+		GET("/hello-world", version("1.2")) {
+			ServerResponse.ok().body("Hello World")
+		}
+	}
+----
+======
+
+The `version` predicate can be:
+
+- Fixed version ("1.2") -- matches the given version only
+- Baseline version ("1.2+") -- matches the given version and above, up to the highest
+xref:web/webmvc/mvc-config/api-version.adoc[supported version].
+
+See xref:web/webmvc-versioning.adoc[API Versioning] for more details on underlying
+infrastructure and support for API Versioning.
+
+
+
+
 [[webmvc-fn-serving-resources]]
 == Serving Resources

@@ -12,6 +12,8 @@ Please, see also related content in:
 - 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
+- xref:web/webmvc-functional.adoc#api-version[Route requests]
+to functional endpoints with an API version

 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
@@ -505,8 +505,10 @@ In this scenario, a `NotAcceptableApiVersionException` results in a 400 response

 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].
+would fail.

+See xref:web/webmvc-versioning.adoc[API Versioning] for more details on underlying
+infrastructure and support for API Versioning.