From e04de95ef2a6714d21737851192e7c7961a31c58 Mon Sep 17 00:00:00 2001 From: rstoyanchev Date: Wed, 14 May 2025 13:00:29 +0100 Subject: [PATCH] Update API versioning ref docs for client side Closes: gh-34569 --- .../modules/ROOT/pages/integration/rest-clients.adoc | 8 +++++++- .../modules/ROOT/pages/testing/webtestclient.adoc | 2 ++ .../modules/ROOT/pages/web/webflux-versioning.adoc | 5 +++++ .../ROOT/pages/web/webflux-webclient/client-builder.adoc | 4 +++- .../modules/ROOT/pages/web/webmvc-versioning.adoc | 4 ++++ 5 files changed, 21 insertions(+), 2 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc index 48e04dac47a..eac23a16cd9 100644 --- a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc +++ b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc @@ -23,7 +23,8 @@ It also exposes a `builder()` with further options: - select the HTTP library to use, see <> - configure message converters, see <> - set a baseUrl -- set default request headers, cookies, path variables +- set default request headers, cookies, path variables, API version +- configure an `ApiVersionInserter` - register interceptors - register request initializers @@ -46,6 +47,8 @@ Java:: .defaultUriVariables(Map.of("variable", "foo")) .defaultHeader("My-Header", "Foo") .defaultCookie("My-Cookie", "Bar") + .defaultVersion("1.2") + .apiVersionInserter(ApiVersionInserter.fromHeader("API-Version").build()) .requestInterceptor(myCustomInterceptor) .requestInitializer(myCustomInitializer) .build(); @@ -64,6 +67,8 @@ Kotlin:: .defaultUriVariables(mapOf("variable" to "foo")) .defaultHeader("My-Header", "Foo") .defaultCookie("My-Cookie", "Bar") + .defaultVersion("1.2") + .apiVersionInserter(ApiVersionInserter.fromHeader("API-Version").build()) .requestInterceptor(myCustomInterceptor) .requestInitializer(myCustomInitializer) .build() @@ -115,6 +120,7 @@ For more details on working with and encoding URIs, see xref:web/webmvc/mvc-uri- If necessary, the HTTP request can be manipulated by adding request headers with `header(String, String)`, `headers(Consumer`, or with the convenience methods `accept(MediaType...)`, `acceptCharset(Charset...)` and so on. For HTTP requests that can contain a body (`POST`, `PUT`, and `PATCH`), additional methods are available: `contentType(MediaType)`, and `contentLength(long)`. +You can set an API version for the request if the client is configured with `ApiVersionInserter`. The request body itself can be set by `body(Object)`, which internally uses <>. Alternatively, the request body can be set using a `ParameterizedTypeReference`, allowing you to use generics. diff --git a/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc index b155859ee5a..ae3bd4f6104 100644 --- a/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc +++ b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc @@ -265,6 +265,7 @@ Java:: client = WebTestClient.bindToController(new TestController()) .configureClient() .baseUrl("/test") + .apiVersionInserter(ApiVersionInserter.fromHeader("API-Version").build()) .build(); ---- @@ -275,6 +276,7 @@ Kotlin:: client = WebTestClient.bindToController(TestController()) .configureClient() .baseUrl("/test") + .apiVersionInserter(ApiVersionInserter.fromHeader("API-Version").build()) .build() ---- ====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc b/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc index 62ff351ba5b..c05bac73c0e 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-versioning.adoc @@ -13,6 +13,11 @@ Please, see also related content in: to map requests to annotated controller methods - Configure API versioning in xref:web/webflux/config.adoc#webflux-config-api-version[WebFlux Config] +TIP: API versioning is also supported on the client side in `RestClient`, `WebClient`, and +xref:integration/rest-clients.adoc#rest-http-interface[HTTP Service] clients, as well as +for testing with `WebTestClient`. + + [[webflux-versioning-strategy]] diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc index d8ed1f3885f..c6ce0f086c3 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc @@ -1,7 +1,7 @@ [[webflux-client-builder]] = Configuration -The simplest way to create a `WebClient` is through one of the static factory methods: +The simplest way to create `WebClient` is through one of the static factory methods: * `WebClient.create()` * `WebClient.create(String baseUrl)` @@ -12,10 +12,12 @@ You can also use `WebClient.builder()` with further options: * `defaultUriVariables`: default values to use when expanding URI templates. * `defaultHeader`: Headers for every request. * `defaultCookie`: Cookies for every request. +* `defaultApiVersion`: API version for every request. * `defaultRequest`: `Consumer` to customize every request. * `filter`: Client filter for every request. * `exchangeStrategies`: HTTP message reader/writer customizations. * `clientConnector`: HTTP client library settings. +* `apiVersionInserter`: to insert API version values in the request * `observationRegistry`: the registry to use for enabling xref:integration/observability.adoc#http-client.webclient[Observability support]. * `observationConvention`: xref:integration/observability.adoc#config[an optional, custom convention to extract metadata] for recorded observations. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc index 2546626fd50..7ea6fad3ecc 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-versioning.adoc @@ -13,6 +13,10 @@ Please, see also related content in: to map requests to annotated controller methods - Configure API versioning in xref:web/webmvc/mvc-config/api-version.adoc[MVC Config] +TIP: API versioning is also supported on the client side in `RestClient`, `WebClient`, and +xref:integration/rest-clients.adoc#rest-http-interface[HTTP Service] clients, as well as +for testing with `WebTestClient`. +