[kotlin][client] Support useJackson3 for the jvm-spring-webclient library

RO
14h ago
+3988-12

Fixes #25078

What

Allows useJackson3 for the Kotlin client library jvm-spring-webclient, generating the
Spring 7 Jackson 3 codecs. Previously useJackson3 was only wired up for jvm-okhttp4 and
jvm-spring-restclient, so webclient users had no way to move off Jackson 2.

No new option is introduced — useJackson3 and useSpringBoot4 already exist; this only
widens where they apply.

Behavior

Mirrors the existing jvm-spring-restclient contract (#24709 / #25130):

  • useSpringBoot4=true on jvm-spring-webclient now auto-enables Jackson 3.
  • An explicit useJackson3=false is honored, keeping the Jackson 2 codecs.
  • useJackson3=true without useSpringBoot4 is rejected with an IllegalArgumentException,
    since the JacksonJsonEncoder/JacksonJsonDecoder types only exist in Spring 7.
  • Spring Boot 3 and Spring Boot 2 webclient output is unchanged.

:warning: Behavior change: projects already generating with
library=jvm-spring-webclient + useSpringBoot4=true will now get Jackson 3 instead of
Jackson 2. Code that uses Serializer.jacksonObjectMapper directly (now a tools.jackson
JsonMapper) may need adjusting. Opt out with useJackson3=false; this is also required
to keep using openApiNullable=true with useSpringBoot4=true.
This matches what jvm-spring-restclient already does — there useSpringBoot4=true has auto-enabled Jackson 3 since #24709 — so the two Spring libraries stay consistent rather than diverging.

How

  • KotlinClientCodegen.java: the auto-enable branch and both validation checks now accept
    jvm-spring-webclient alongside jvm-spring-restclient; the "requires useSpringBoot4"
    message is generalised to name the actual library.
  • libraries/jvm-spring-webclient/api.mustache: imports JacksonJsonEncoder/JacksonJsonDecoder
    and registers them via defaultCodecs().jacksonJsonEncoder(...) /
    .jacksonJsonDecoder(...) when useJackson3 is set, otherwise the existing Jackson2Json*
    path. com.fasterxml.jackson.annotation.JsonProperty stays, as Jackson 3 keeps the 2.x
    annotations package.
  • build.gradle.mustache: the Java 17 toolchain block is now emitted for useSpringBoot4
    as well, without duplicating it when both Boot flags are set.
  • Library description and the useSpringBoot4 option text updated; docs/generators/kotlin.md
    re-exported.

Tests

Five new cases in KotlinClientCodegenModelTest covering auto-enable, the explicit
useJackson3=false opt-out, the two rejection paths, unchanged Spring Boot 3 output, and
an explicit useSpringBoot4=false not enabling Jackson 3.

./mvnw -pl modules/openapi-generator test -Dtest='KotlinClientCodegen*'

→ 115 tests, 0 failures.

Samples

New sample samples/client/petstore/kotlin-jvm-spring-4-webclient-jackson3, modelled on
kotlin-jvm-spring-4-restclient-jackson3, plus its bin/configs entry and an entry in
.github/workflows/samples-kotlin-client.yaml. All existing Kotlin samples are byte-identical.
The new sample builds on JDK 17 (./gradlew build -x test → BUILD SUCCESSFUL) against
Spring Boot 4.1.0 / Spring Framework 7.0.8.

PR checklist

  • Read the contribution guidelines.
  • Ran the build and regenerated samples and docs.
  • @mentioned the technical committee members.

cc @karismann @Zomzog @andrewemery @4brunu @yutaka0m @stefankoppier @e5l @AndreyVMarkelov


Summary by cubic

Adds useJackson3 support for the Kotlin jvm-spring-webclient library so generated clients can use Spring 7's Jackson 3 codecs instead of Jackson 2.

useSpringBoot4=true now auto-enables Jackson 3, matching jvm-spring-restclient. An explicit useJackson3=false keeps the Jackson 2 codecs, and useJackson3=true without useSpringBoot4 fails with IllegalArgumentException. Projects already using jvm-spring-webclient with useSpringBoot4=true will switch from Jackson 2 to Jackson 3; set useJackson3=false to stay on Jackson 2.

Changes

  • Swaps the Jackson encoder and decoder imports in the api.mustache template based on useJackson3.
  • Emits the Kotlin Java 17 toolchain block for useSpringBoot4 in the generated build.gradle.
  • Adds codegen tests covering auto-enable, the explicit opt-out, both rejection paths, and useSpringBoot4=false, plus a new petstore sample kotlin-jvm-spring-4-webclient-jackson3.