feat(kotlin-client): add Jackson 3 support with useJackson3 option

Wire the existing AbstractKotlinCodegen Jackson 3 infrastructure into
the kotlin client generator. When useJackson3=true (requires
serializationLibrary=jackson), all templates use the tools.jackson
package instead of com.fasterxml.jackson, and build.gradle pulls
jackson-module-kotlin 3.0.1 without the separate JSR-310 module.

- Register useJackson3 CLI option in KotlinClientCodegen
- Add validation: requires jackson serialization, incompatible with openApiNullable
- Replace hardcoded com.fasterxml.jackson with {{jacksonPackage}} in all
  model, serializer, and library-specific templates
- Make JavaTimeModule conditional (not needed in Jackson 3) for jvm-ktor
- Add Jackson 3 dependency block in build.gradle.mustache
- Add tests for validation and generated output
- Add kotlin-jackson3 sample config and generated sample
- Add sample to CI workflow matrix
- Regenerate generator docs

Author: yonatankarp

.github/workflows/samples-kotlin-client.yaml

@@ -26,6 +26,7 @@ jobs:
           - samples/client/petstore/kotlin-explicit
           - samples/client/petstore/kotlin-gson
           - samples/client/petstore/kotlin-jackson
+          - samples/client/petstore/kotlin-jackson3
           - samples/client/petstore/kotlin-model-prefix-type-mappings
           # needs Android configured
           #- samples/client/petstore/kotlin-json-request-string

bin/configs/kotlin-jackson3.yaml

@@ -0,0 +1,10 @@
+generatorName: kotlin
+outputDir: samples/client/petstore/kotlin-jackson3
+inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore.yaml
+templateDir: modules/openapi-generator/src/main/resources/kotlin-client
+additionalProperties:
+  serializationLibrary: jackson
+  useJackson3: "true"
+  artifactId: kotlin-petstore-jackson3
+  enumPropertyNaming: UPPERCASE
+  enumUnknownDefaultCase: "true"

docs/generators/kotlin.md

@@ -49,6 +49,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). Requires serializationLibrary=jackson. Incompatible with openApiNullable.| |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

@@ -293,6 +293,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). Requires serializationLibrary=jackson. Incompatible with openApiNullable."));
     }
 
     @Override
@@ -464,6 +467,16 @@ public void processOpts() {
             additionalProperties.put(this.serializationLibrary.name(), true);
         }
 
+        if (isUseJackson3()) {
+            if (this.serializationLibrary != SERIALIZATION_LIBRARY_TYPE.jackson) {
+                throw new IllegalArgumentException("useJackson3 requires serializationLibrary=jackson");
+            }
+            if (additionalProperties.containsKey("openApiNullable")
+                    && Boolean.parseBoolean(additionalProperties.get("openApiNullable").toString())) {
+                throw new IllegalArgumentException("openApiNullable cannot be set with useJackson3");
+            }
+        }
+
         if (additionalProperties.containsKey(MAP_FILE_BINARY_TO_BYTE_ARRAY)) {
             setMapFileBinaryToByteArray(convertPropertyToBooleanAndWriteBack(MAP_FILE_BINARY_TO_BYTE_ARRAY));
         }

modules/openapi-generator/src/main/resources/kotlin-client/anyof_class.mustache

@@ -18,12 +18,12 @@ import com.squareup.moshi.JsonClass
 {{/moshi}}
 {{#jackson}}
 {{#enumUnknownDefaultCase}}
-import com.fasterxml.jackson.annotation.JsonEnumDefaultValue
+import {{jacksonPackage}}.annotation.JsonEnumDefaultValue
 {{/enumUnknownDefaultCase}}
-import com.fasterxml.jackson.annotation.JsonProperty
+import {{jacksonPackage}}.annotation.JsonProperty
 {{#discriminator}}
-import com.fasterxml.jackson.annotation.JsonSubTypes
-import com.fasterxml.jackson.annotation.JsonTypeInfo
+import {{jacksonPackage}}.annotation.JsonSubTypes
+import {{jacksonPackage}}.annotation.JsonTypeInfo
 {{/discriminator}}
 {{/jackson}}
 {{#kotlinx_serialization}}

modules/openapi-generator/src/main/resources/kotlin-client/build.gradle.mustache

@@ -163,8 +163,13 @@ dependencies {
     {{/gson}}
     {{#jackson}}
     implementation "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"
+    {{#useJackson3}}
+    implementation "tools.jackson.module:jackson-module-kotlin:3.0.1"
+    {{/useJackson3}}
+    {{^useJackson3}}
     implementation "com.fasterxml.jackson.module:jackson-module-kotlin:2.20.0"
     implementation "com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.20.0"
+    {{/useJackson3}}
     {{/jackson}}
     {{#kotlinx_serialization}}
     implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0"

modules/openapi-generator/src/main/resources/kotlin-client/data_class.mustache

@@ -19,13 +19,13 @@ import com.squareup.moshi.JsonClass
 {{/moshi}}
 {{#jackson}}
 {{#enumUnknownDefaultCase}}
-import com.fasterxml.jackson.annotation.JsonEnumDefaultValue
+import {{jacksonPackage}}.annotation.JsonEnumDefaultValue
 {{/enumUnknownDefaultCase}}
-import com.fasterxml.jackson.annotation.JsonProperty
+import {{jacksonPackage}}.annotation.JsonProperty
 {{#discriminator}}
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties
-import com.fasterxml.jackson.annotation.JsonSubTypes
-import com.fasterxml.jackson.annotation.JsonTypeInfo
+import {{jacksonPackage}}.annotation.JsonIgnoreProperties
+import {{jacksonPackage}}.annotation.JsonSubTypes
+import {{jacksonPackage}}.annotation.JsonTypeInfo
 {{/discriminator}}
 {{/jackson}}
 {{#kotlinx_serialization}}

modules/openapi-generator/src/main/resources/kotlin-client/enum_class.mustache

@@ -7,12 +7,12 @@ import com.squareup.moshi.Json
 import com.squareup.moshi.JsonClass
 {{/moshi}}
 {{#jackson}}
-import com.fasterxml.jackson.annotation.JsonCreator
+import {{jacksonPackage}}.annotation.JsonCreator
 {{#enumUnknownDefaultCase}}
-import com.fasterxml.jackson.annotation.JsonEnumDefaultValue
+import {{jacksonPackage}}.annotation.JsonEnumDefaultValue
 {{/enumUnknownDefaultCase}}
-import com.fasterxml.jackson.annotation.JsonProperty
-import com.fasterxml.jackson.annotation.JsonValue
+import {{jacksonPackage}}.annotation.JsonProperty
+import {{jacksonPackage}}.annotation.JsonValue
 import kotlin.jvm.JvmStatic
 {{/jackson}}
 {{#kotlinx_serialization}}

modules/openapi-generator/src/main/resources/kotlin-client/jvm-common/infrastructure/Serializer.kt.mustache

@@ -30,11 +30,11 @@ import kotlinx.datetime.LocalTime
 import java.util.UUID
 {{/gson}}
 {{#jackson}}
-import com.fasterxml.jackson.databind.DeserializationFeature
-import com.fasterxml.jackson.databind.ObjectMapper
-import com.fasterxml.jackson.databind.SerializationFeature
-import com.fasterxml.jackson.annotation.JsonInclude
-import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
+import {{jacksonPackage}}.databind.DeserializationFeature
+import {{jacksonPackage}}.databind.ObjectMapper
+import {{jacksonPackage}}.databind.SerializationFeature
+import {{jacksonPackage}}.annotation.JsonInclude
+import {{jacksonPackage}}.module.kotlin.jacksonObjectMapper
 {{/jackson}}
 {{#kotlinx_serialization}}
 import java.math.BigDecimal