feat(kotlin-spring): add Spring Boot 4 and Jackson 3 support (#23154)

* feat(kotlin): add Jackson 3 infrastructure to AbstractKotlinCodegen

* feat(kotlin-spring): add useSpringBoot4 and useJackson3 flags

* feat(kotlin-spring): update template selection for Spring Boot 4

* feat(kotlin-spring): add SB4 templates for all libraries

* test(kotlin-spring): add tests for Spring Boot 4 and Jackson 3 support

* feat(kotlin-spring): add kotlin-springboot-4 sample with Jackson 3

* docs(kotlin-spring): document useSpringBoot4 and useJackson3 options

* fix(kotlin-spring): update Gradle templates to Kotlin 2.2 JvmTarget DSL and bump CI Gradle

- Replace deprecated kotlinOptions.jvmTarget with kotlin.compilerOptions DSL
- Upgrade Gradle wrapper to 8.14 for Kotlin 2.2 compatibility
- Add kotlin-springboot-4 sample to JDK17 CI matrix
- Regenerate sample with updated templates

* fix(kotlin-spring): register useJackson3 CLI option and use Gradle 8.14 for SB4

- Add addSwitch for useJackson3 in KotlinSpringServerCodegen so it
  appears in auto-generated docs
- Update gradle-wrapper.properties.mustache templates to use Gradle 8.14
  when useSpringBoot4 is enabled (required minimum for Spring Boot 4)

* fix(kotlin-client): fix Jackson 3 package imports and add ktor/spring-restclient support

Replace hardcoded com.fasterxml.jackson imports with {{jacksonPackage}} template
variable across all kotlin-client templates so generated code compiles correctly
when useJackson3=true. Also fix trailing space in OAuth Bearer header, enable
useJackson3 for jvm-ktor (Ktor 3.4.0) and jvm-spring-restclient (Spring Boot 4),
and add conditional Jackson 3 dependencies in build.gradle.

* Revert "fix(kotlin-client): fix Jackson 3 package imports and add ktor/spring-restclient support"

Block useJackson3 for kotlin-client with a clear error until client
template support is added in a follow-up PR.

* ci: retrigger CI checks

* fix(kotlin-spring): replace legacy oauth2 starter and add Jackson exclusivity tests

Replace deprecated spring-cloud-starter-oauth2:2.2.5.RELEASE with
spring-boot-starter-oauth2-client in SB4 templates, as the legacy
starter is pre-Jakarta and incompatible with Spring Boot 4.

Add negative assertions to Jackson dependency tests to ensure Jackson 2
and Jackson 3 artifacts are mutually exclusive.

* feat(kotlin-spring): default to Jackson 3 when Spring Boot 4 is enabled

Spring Boot 4 ships with Jackson 3 out of the box, so useJackson3 now
defaults to true when useSpringBoot4 is enabled and the user hasn't
explicitly set useJackson3.

* fix(kotlin-spring): declare springdoc version property regardless of useSwaggerUI

The springdoc-openapi.version Maven property was only declared when
useSwaggerUI=true, but the springdoc core dependency (used when
useSwaggerUI=false) also references it, causing an undefined property.

* fix(kotlin-spring): use modern OAuth2 client config for Spring Boot 4 spring-cloud library

Add useSpringBoot4 conditionals to clientConfiguration.mustache so SB4
uses OAuth2AuthorizedClientManager instead of legacy OAuth2FeignRequestInterceptor
and *ResourceDetails classes that don't exist in Spring Boot 4.

* fix(kotlin-spring): default Jackson 3 when Spring Boot 4 set via setter or additionalProperties

The Jackson 3 defaulting logic only checked additionalProperties map,
so calling setUseSpringBoot4(true) via the Java API skipped the default.
Now checks both the field value and the map.

* fix(kotlin-spring): add trailing newline to clientConfiguration template

* Trigger CI

* clean up conditions

* fix(kotlin-spring): remove SB4+Jackson2 test since SB4 unconditionally implies Jackson 3

Spring Boot 4 ships with Jackson 3 — there is no supported SB4+Jackson2
combination, so the test was asserting an invalid scenario.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: yonatankarp

.github/workflows/samples-kotlin-server-jdk17.yaml

@@ -27,7 +27,7 @@ on:
       # - samples/server/petstore/kotlin-spring-default/**
 
 env:
-  GRADLE_VERSION: '8.11'
+  GRADLE_VERSION: '8.14'
 
 jobs:
   build:
@@ -48,6 +48,7 @@ jobs:
           - samples/server/petstore/kotlin-springboot-additionalproperties
           - samples/server/petstore/kotlin-springboot-delegate-nodefaults
           - samples/server/petstore/kotlin-springboot-request-cookie
+          - samples/server/petstore/kotlin-springboot-4
           - samples/server/petstore/kotlin-server/jaxrs-spec
           - samples/server/petstore/kotlin-server/jaxrs-spec-mutiny
           - samples/server/petstore/kotlin-server/javalin

.github/workflows/samples-kotlin-server-jdk21.yaml

@@ -13,7 +13,7 @@ on:
       - 'samples/server/petstore/kotlin-server-required-and-nullable-properties/**'
 
 env:
-  GRADLE_VERSION: '8.11'
+  GRADLE_VERSION: '8.14'
 
 jobs:
   build:

bin/configs/kotlin-spring-boot-4.yaml

@@ -0,0 +1,16 @@
+generatorName: kotlin-spring
+outputDir: samples/server/petstore/kotlin-springboot-4
+library: spring-boot
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
+templateDir: modules/openapi-generator/src/main/resources/kotlin-spring
+additionalProperties:
+  documentationProvider: none
+  annotationLibrary: none
+  useSwaggerUI: "false"
+  serviceImplementation: "true"
+  serializableModel: "true"
+  beanValidations: "true"
+  useSpringBoot4: "true"
+  useJackson3: "true"
+  requestMappingMode: api_interface
+  gradleBuildFile: "true"

docs/generators/kotlin-spring.md

@@ -59,9 +59,11 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useBeanValidation|Use BeanValidation API annotations to validate data types| |true|
 |useFeignClientUrl|Whether to generate Feign client with url parameter.| |true|
 |useFlowForArrayReturnType|Whether to use Flow for array/collection return types when reactive is enabled. If false, will use List instead.| |true|
+|useJackson3|Use Jackson 3 dependencies (tools.jackson package). Only available with `useSpringBoot4`. Defaults to true when `useSpringBoot4` is enabled. Incompatible with `openApiNullable`.| |false|
 |useResponseEntity|Whether (when false) to return actual type (e.g. List<Fruit>) and handle non-happy path responses via exceptions flow or (when true) return entire ResponseEntity (e.g. ResponseEntity<List<Fruit>>). If disabled, method are annotated using a @ResponseStatus annotation, which has the status of the first response declared in the Api definition| |true|
 |useSealedResponseInterfaces|Generate sealed interfaces for endpoint responses that all possible response types implement. Allows controllers to return any valid response type in a type-safe manner (e.g., sealed interface CreateUserResponse implemented by User, ConflictResponse, ErrorResponse)| |false|
 |useSpringBoot3|Generate code and provide dependencies for use with Spring Boot ≥ 3 (use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.| |false|
+|useSpringBoot4|Generate code and provide dependencies for use with Spring Boot 4.x. Enabling this option will also enable `useJakartaEe`.| |false|
 |useSwaggerUI|Open the OpenApi specification in swagger-ui. Will also import and configure needed dependencies| |true|
 |useTags|Whether to use tags for creating interface and controller class names| |false|
 |xKotlinImplementsFieldsSkip|A list of fields per schema name that should NOT be created with `override` keyword despite their presence in vendor extension `x-kotlin-implements-fields` for the schema. Example: yaml `xKotlinImplementsFieldsSkip: Pet: [photoUrls]` skips `override` for `photoUrls` in schema `Pet`| |empty map|

docs/generators/kotlin.md

@@ -50,6 +50,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |sourceFolder|source folder for generated code| |src/main/kotlin|
 |supportAndroidApiLevel25AndBelow|[WARNING] This flag will generate code that has a known security vulnerability. It uses `kotlin.io.createTempFile` instead of `java.nio.file.Files.createTempFile` in order to support Android API level 25 and below. For more info, please check the following links https://github.com/OpenAPITools/openapi-generator/security/advisories/GHSA-23x4-m842-fmwf, https://github.com/OpenAPITools/openapi-generator/pull/9284| |false|
 |useCoroutines|Whether to use the Coroutines adapter with the retrofit2 library.| |false|
+|useJackson3|Use Jackson 3 dependencies (tools.jackson package). Not yet supported for kotlin-client; reserved for future use.| |false|
 |useNonAsciiHeaders|Allow to use non-ascii headers with the okhttp library| |false|
 |useResponseAsReturnType|When using retrofit2 and coroutines, use `Response`<`T`> as return type instead of `T`.| |true|
 |useRxJava3|Whether to use the RxJava3 adapter with the retrofit2 library.| |false|

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractKotlinCodegen.java

@@ -56,6 +56,10 @@ public abstract class AbstractKotlinCodegen extends DefaultCodegen implements Co
 
     public static final String JAVAX_PACKAGE = "javaxPackage";
     public static final String USE_JAKARTA_EE = "useJakartaEe";
+    public static final String USE_JACKSON_3 = "useJackson3";
+    public static final String JACKSON2_PACKAGE = "com.fasterxml.jackson";
+    public static final String JACKSON3_PACKAGE = "tools.jackson";
+    public static final String JACKSON_PACKAGE = "jacksonPackage";
     public static final String SCHEMA_IMPLEMENTS = "schemaImplements";
     public static final String SCHEMA_IMPLEMENTS_FIELDS = "schemaImplementsFields";
     public static final String X_KOTLIN_IMPLEMENTS_SKIP = "xKotlinImplementsSkip";
@@ -80,6 +84,7 @@ public abstract class AbstractKotlinCodegen extends DefaultCodegen implements Co
     protected boolean serializableModel = false;
 
     @Setter protected boolean useJakartaEe = false;
+    @Getter @Setter protected boolean useJackson3 = false;
 
     @Setter protected boolean nonPublicApi = false;
 
@@ -569,6 +574,17 @@ public void processOpts() {
         } else {
             applyJavaxPackage();
         }
+
+        if (additionalProperties.containsKey(USE_JACKSON_3)) {
+            setUseJackson3(Boolean.parseBoolean(additionalProperties.get(USE_JACKSON_3).toString()));
+        }
+        additionalProperties.put(USE_JACKSON_3, useJackson3);
+
+        if (useJackson3) {
+            applyJackson3Package();
+        } else {
+            applyJackson2Package();
+        }
     }
 
     protected boolean isModelMutable() {
@@ -844,6 +860,14 @@ protected void applyJakartaPackage() {
         writePropertyBack(JAVAX_PACKAGE, "jakarta");
     }
 
+    protected void applyJackson2Package() {
+        writePropertyBack(JACKSON_PACKAGE, JACKSON2_PACKAGE);
+    }
+
+    protected void applyJackson3Package() {
+        writePropertyBack(JACKSON_PACKAGE, JACKSON3_PACKAGE);
+    }
+
     @Override
     protected boolean isReservedWord(String word) {
         // We want case-sensitive escaping, to avoid unnecessary backtick-escaping.

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinClientCodegen.java

@@ -298,6 +298,9 @@ public KotlinClientCodegen() {
 
         cliOptions.add(CliOption.newBoolean(USE_NON_ASCII_HEADERS, "Allow to use non-ascii headers with the okhttp library"));
         cliOptions.add(CliOption.newBoolean(USE_RESPONSE_AS_RETURN_TYPE, "When using retrofit2 and coroutines, use `Response`<`T`> as return type instead of `T`.", true));
+
+        cliOptions.add(CliOption.newBoolean(USE_JACKSON_3,
+            "Use Jackson 3 dependencies (tools.jackson package). Not yet supported for kotlin-client; reserved for future use."));
     }
 
     @Override
@@ -466,6 +469,11 @@ public void processOpts() {
             convertPropertyToBooleanAndWriteBack(USE_SPRING_BOOT3);
         }
 
+        if (isUseJackson3()) {
+            throw new IllegalArgumentException(
+                "useJackson3 is not yet supported for kotlin-client. Jackson 3 support for kotlin-client will be added in a future release.");
+        }
+
         if (additionalProperties.containsKey(CodegenConstants.SERIALIZATION_LIBRARY)) {
             setSerializationLibrary((String) additionalProperties.get(CodegenConstants.SERIALIZATION_LIBRARY));
             additionalProperties.put(this.serializationLibrary.name(), true);

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java

@@ -91,6 +91,7 @@ public class KotlinSpringServerCodegen extends AbstractKotlinCodegen
     public static final String DECLARATIVE_INTERFACE_REACTIVE_MODE = "declarativeInterfaceReactiveMode";
 
     public static final String USE_SPRING_BOOT3 = "useSpringBoot3";
+    public static final String USE_SPRING_BOOT4 = "useSpringBoot4";
     public static final String INCLUDE_HTTP_REQUEST_CONTEXT = "includeHttpRequestContext";
     public static final String USE_FLOW_FOR_ARRAY_RETURN_TYPE = "useFlowForArrayReturnType";
     public static final String REQUEST_MAPPING_OPTION = "requestMappingMode";
@@ -168,6 +169,8 @@ public String getDescription() {
 
     @Getter @Setter
     protected boolean useSpringBoot3 = false;
+    @Getter @Setter
+    protected boolean useSpringBoot4 = false;
     protected RequestMappingMode requestMappingMode = RequestMappingMode.controller;
     private DocumentationProvider documentationProvider;
     private AnnotationLibrary annotationLibrary;
@@ -254,6 +257,8 @@ public KotlinSpringServerCodegen() {
                 "@RestController annotations. May be used to prevent bean names clash if multiple generated libraries" +
                 " (contexts) added to single project.", beanQualifiers);
         addSwitch(USE_SPRING_BOOT3, "Generate code and provide dependencies for use with Spring Boot ≥ 3 (use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.", useSpringBoot3);
+        addSwitch(USE_SPRING_BOOT4, "Generate code and provide dependencies for use with Spring Boot 4.x. Enabling this option will also enable `useJakartaEe`.", useSpringBoot4);
+        addSwitch(USE_JACKSON_3, "Use Jackson 3 dependencies (tools.jackson package). Only available with `useSpringBoot4`. Defaults to true when `useSpringBoot4` is enabled. Incompatible with `openApiNullable`.", useJackson3);
         addSwitch(USE_FLOW_FOR_ARRAY_RETURN_TYPE, "Whether to use Flow for array/collection return types when reactive is enabled. If false, will use List instead.", useFlowForArrayReturnType);
         addSwitch(INCLUDE_HTTP_REQUEST_CONTEXT, "Whether to include HttpServletRequest (blocking) or ServerWebExchange (reactive) as additional parameter in generated methods.", includeHttpRequestContext);
         addSwitch(USE_RESPONSE_ENTITY,
@@ -419,6 +424,13 @@ public String getHelp() {
 
     @Override
     public void processOpts() {
+        boolean springBoot4Enabled = useSpringBoot4
+                || (additionalProperties.containsKey(USE_SPRING_BOOT4)
+                    && convertPropertyToBoolean(USE_SPRING_BOOT4));
+        if (springBoot4Enabled) {
+            additionalProperties.put(USE_JACKSON_3, "true");
+        }
+
         super.processOpts();
 
         if (DocumentationProvider.SPRINGFOX.equals(getDocumentationProvider())) {
@@ -467,6 +479,9 @@ public void processOpts() {
         if (additionalProperties.containsKey(USE_SPRING_BOOT3)) {
             this.setUseSpringBoot3(convertPropertyToBoolean(USE_SPRING_BOOT3));
         }
+        if (additionalProperties.containsKey(USE_SPRING_BOOT4)) {
+            this.setUseSpringBoot4(convertPropertyToBoolean(USE_SPRING_BOOT4));
+        }
         if (additionalProperties.containsKey(INCLUDE_HTTP_REQUEST_CONTEXT)) {
             this.setIncludeHttpRequestContext(convertPropertyToBoolean(INCLUDE_HTTP_REQUEST_CONTEXT));
         }
@@ -493,6 +508,11 @@ public void processOpts() {
         // used later in recursive import in postProcessingModels
         importMapping.put("com.fasterxml.jackson.annotation.JsonProperty", "com.fasterxml.jackson.annotation.JsonCreator");
 
+        if (isUseJackson3()) {
+            // Override databind imports for Jackson 3
+            importMapping.put("JsonDeserialize", "tools.jackson.databind.annotation.JsonDeserialize");
+        }
+
         // Spring-specific import mappings for x-spring-paginated support
         importMapping.put("ApiIgnore", "springfox.documentation.annotations.ApiIgnore");
         importMapping.put("ParameterObject", "org.springdoc.api.annotations.ParameterObject");
@@ -634,7 +654,9 @@ public void processOpts() {
             }
         }
         if (SPRING_DECLARATIVE_HTTP_INTERFACE_LIBRARY.equals(library)) {
-            this.setUseSpringBoot3(true);
+            if (!isUseSpringBoot4()) {
+                this.setUseSpringBoot3(true);
+            }
             this.setInterfaceOnly(true);
             this.setUseFeignClient(false);
             this.setSkipDefaultInterface(true);
@@ -689,7 +711,20 @@ public void processOpts() {
             this.setAutoXSpringPaginated(convertPropertyToBoolean(AUTO_X_SPRING_PAGINATED));
         }
         writePropertyBack(AUTO_X_SPRING_PAGINATED, autoXSpringPaginated);
-        if (isUseSpringBoot3()) {
+        if (isUseSpringBoot3() && isUseSpringBoot4()) {
+            throw new IllegalArgumentException("Choose between Spring Boot 3 and Spring Boot 4");
+        }
+
+        if (isUseJackson3() && !isUseSpringBoot4()) {
+            throw new IllegalArgumentException("useJackson3 is only available with Spring Boot >= 4");
+        }
+
+        if (isUseJackson3() && additionalProperties.containsKey("openApiNullable")
+                && Boolean.parseBoolean(additionalProperties.get("openApiNullable").toString())) {
+            throw new IllegalArgumentException("openApiNullable cannot be set with useJackson3");
+        }
+
+        if (isUseSpringBoot3() || isUseSpringBoot4()) {
             if (DocumentationProvider.SPRINGFOX.equals(getDocumentationProvider())) {
                 throw new IllegalArgumentException(DocumentationProvider.SPRINGFOX.getPropertyName() + " is not supported with Spring Boot > 3.x");
             }
@@ -701,6 +736,7 @@ public void processOpts() {
             applyJakartaPackage();
         }
         writePropertyBack(USE_SPRING_BOOT3, isUseSpringBoot3());
+        writePropertyBack(USE_SPRING_BOOT4, isUseSpringBoot4());
 
         modelTemplateFiles.put("model.mustache", ".kt");
 
@@ -742,14 +778,18 @@ public void processOpts() {
             supportingFiles.add(new SupportingFile("apiUtil.mustache",
                     (sourceFolder + File.separator + apiPackage).replace(".", java.io.File.separator), "ApiUtil.kt"));
 
-            if (isUseSpringBoot3()) {
+            if (isUseSpringBoot4()) {
+                supportingFiles.add(new SupportingFile("pom-sb4.mustache", "", "pom.xml"));
+            } else if (isUseSpringBoot3()) {
                 supportingFiles.add(new SupportingFile("pom-sb3.mustache", "", "pom.xml"));
             } else {
                 supportingFiles.add(new SupportingFile("pom.mustache", "", "pom.xml"));
             }
 
             if (this.gradleBuildFile) {
-                if (isUseSpringBoot3()) {
+                if (isUseSpringBoot4()) {
+                    supportingFiles.add(new SupportingFile("buildGradle-sb4-Kts.mustache", "", "build.gradle.kts"));
+                } else if (isUseSpringBoot3()) {
                     supportingFiles.add(new SupportingFile("buildGradle-sb3-Kts.mustache", "", "build.gradle.kts"));
                 } else {
                     supportingFiles.add(new SupportingFile("buildGradleKts.mustache", "", "build.gradle.kts"));
@@ -788,14 +828,18 @@ public void processOpts() {
         if (library.equals(SPRING_CLOUD_LIBRARY)) {
             LOGGER.info("Setup code generator for Kotlin Spring Cloud Client");
 
-            if (isUseSpringBoot3()) {
+            if (isUseSpringBoot4()) {
+                supportingFiles.add(new SupportingFile("pom-sb4.mustache", "pom.xml"));
+            } else if (isUseSpringBoot3()) {
                 supportingFiles.add(new SupportingFile("pom-sb3.mustache", "pom.xml"));
             } else {
                 supportingFiles.add(new SupportingFile("pom.mustache", "pom.xml"));
             }
 
             if (this.gradleBuildFile) {
-                if (isUseSpringBoot3()) {
+                if (isUseSpringBoot4()) {
+                    supportingFiles.add(new SupportingFile("buildGradle-sb4-Kts.mustache", "build.gradle.kts"));
+                } else if (isUseSpringBoot3()) {
                     supportingFiles.add(new SupportingFile("buildGradle-sb3-Kts.mustache", "build.gradle.kts"));
                 } else {
                     supportingFiles.add(new SupportingFile("buildGradleKts.mustache", "build.gradle.kts"));
@@ -827,10 +871,18 @@ public void processOpts() {
         if (library.equals(SPRING_DECLARATIVE_HTTP_INTERFACE_LIBRARY)) {
             LOGGER.info("Setup code generator for Kotlin Spring Declarative Http interface");
 
-            supportingFiles.add(new SupportingFile("pom-sb3.mustache", "pom.xml"));
+            if (isUseSpringBoot4()) {
+                supportingFiles.add(new SupportingFile("pom-sb4.mustache", "pom.xml"));
+            } else {
+                supportingFiles.add(new SupportingFile("pom-sb3.mustache", "pom.xml"));
+            }
 
             if (this.gradleBuildFile) {
-                supportingFiles.add(new SupportingFile("buildGradle-sb3-Kts.mustache", "build.gradle.kts"));
+                if (isUseSpringBoot4()) {
+                    supportingFiles.add(new SupportingFile("buildGradle-sb4-Kts.mustache", "build.gradle.kts"));
+                } else {
+                    supportingFiles.add(new SupportingFile("buildGradle-sb3-Kts.mustache", "build.gradle.kts"));
+                }
                 supportingFiles.add(new SupportingFile("settingsGradle.mustache", "settings.gradle"));
 
                 String gradleWrapperPackage = "gradle.wrapper";