feature/jackson3 native (fixes #22294)

[thorstenhirsch]

Add Jackson 3 support to java-native.

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• If your PR solves a reported issue, reference it using GitHub's linking syntax (e.g., having "fixes #123" present in the PR description)
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

@bbdouglas (2017/07) @sreeshas (2017/08) @jfiala (2017/08) @lukoyanov (2017/09) @cbornet (2017/09) @jeff9finger (2018/01) @karismann (2019/03) @Zomzog (2019/04) @lwlee2608 (2019/10) @martin-mfg (2023/08)

---

Summary by cubic

Adds opt-in Jackson 3 support to the Java native client generator, enabling modern Jackson APIs while keeping Jackson 2 as the default. This adds a new flag, switches imports/config when enabled, and updates docs, tests, and samples.

• New Features

  • Added additionalProperty useJackson3 for the Java native library.
  • Updated templates to use tools.jackson.* and Jackson 3 time/RFC3339 handling.
  • Conditional Maven/Gradle deps for tools.jackson (jackson3_version=3.0.4).
  • Added sample client: samples/client/petstore/java/native-jackson3 and a unit test.

• Migration

  • Default remains Jackson 2. To opt in: set additionalProperties.useJackson3=true (library=native only).
  • Regenerate clients; no other changes required.
  • Requires Java 11+ and Jackson 3.0.4+.

^{Written for commit 8f7a982. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 304 files

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/main/resources/Java/libraries/native/pom.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/Java/libraries/native/pom.mustache:268">
P1: Potential compile failure: When useJackson3=true, jackson-databind-nullable dependency is excluded from POM, but pojo.mustache still generates JsonNullable type references if openApiNullable is enabled (default). This causes compilation errors due to missing import org.openapitools.jackson.nullable.JsonNullable.</violation>
</file>

<file name="samples/client/petstore/java/native-jackson3/build.gradle">

<violation number="1" location="samples/client/petstore/java/native-jackson3/build.gradle:87">
P2: JUnit 5 is incompletely configured - missing engine dependency and useJUnitPlatform()</violation>
</file>

<file name="modules/openapi-generator/src/main/resources/Java/libraries/native/model.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/Java/libraries/native/model.mustache:50">
P0: Incorrect Jackson 3 annotation package imports. The `jackson-annotations` module deliberately kept `com.fasterxml.jackson.annotation.*` package in Jackson 3 for backward compatibility - only core modules moved to `tools.jackson.*`. Fix: annotation imports should remain as `com.fasterxml.jackson.annotation.*` in the useJackson3 section.</violation>
</file>

<file name="samples/client/petstore/java/native-jackson3/docs/DefaultApi.md">

<violation number="1" location="samples/client/petstore/java/native-jackson3/docs/DefaultApi.md:73">
P2: Documentation method signature contains extra 'fooGet' token, resulting in invalid Java syntax 'ApiResponse<FooGetDefaultResponse> fooGet fooGetWithHttpInfo()'. Should be 'ApiResponse<FooGetDefaultResponse> fooGetWithHttpInfo()'.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P0: Incorrect Jackson 3 annotation package imports. The jackson-annotations module deliberately kept com.fasterxml.jackson.annotation.* package in Jackson 3 for backward compatibility - only core modules moved to tools.jackson.*. Fix: annotation imports should remain as com.fasterxml.jackson.annotation.* in the useJackson3 section.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/Java/libraries/native/model.mustache, line 50:

<comment>Incorrect Jackson 3 annotation package imports. The `jackson-annotations` module deliberately kept `com.fasterxml.jackson.annotation.*` package in Jackson 3 for backward compatibility - only core modules moved to `tools.jackson.*`. Fix: annotation imports should remain as `com.fasterxml.jackson.annotation.*` in the useJackson3 section.</comment>

<file context>
@@ -31,13 +37,24 @@ import {{import}};
 {{/vendorExtensions.x-has-readonly-properties}}
+{{/useJackson3}}
+{{#useJackson3}}
+import tools.jackson.annotation.JsonPropertyOrder;
+{{#withXml}}
+import tools.jackson.dataformat.xml.annotation.*;
</file context>

[cubic-dev-ai]

P1: Potential compile failure: When useJackson3=true, jackson-databind-nullable dependency is excluded from POM, but pojo.mustache still generates JsonNullable type references if openApiNullable is enabled (default). This causes compilation errors due to missing import org.openapitools.jackson.nullable.JsonNullable.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/Java/libraries/native/pom.mustache, line 268:

<comment>Potential compile failure: When useJackson3=true, jackson-databind-nullable dependency is excluded from POM, but pojo.mustache still generates JsonNullable type references if openApiNullable is enabled (default). This causes compilation errors due to missing import org.openapitools.jackson.nullable.JsonNullable.</comment>

<file context>
@@ -242,6 +243,30 @@
+            <artifactId>jackson-datatype-jsr310</artifactId>
+            <version>${jackson3-version}</version>
+        </dependency>
+        <!-- Note: jackson-databind-nullable is not yet available for Jackson 3 -->
+        {{/useJackson3}}
 
</file context>

[cubic-dev-ai]

P2: JUnit 5 is incompletely configured - missing engine dependency and useJUnitPlatform()

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3/build.gradle, line 87:

<comment>JUnit 5 is incompletely configured - missing engine dependency and useJUnitPlatform()</comment>

<file context>
@@ -0,0 +1,111 @@
+    implementation "jakarta.annotation:jakarta.annotation-api:$jakarta_annotation_version"
+    implementation "org.apache.httpcomponents:httpmime:$httpmime_version"
+    implementation "org.apache.commons:commons-lang3:$commons_lang3_version"
+    testImplementation "org.junit.jupiter:junit-jupiter-api:$junit_version"
+}
+
</file context>

[cubic-dev-ai]

P2: Documentation method signature contains extra 'fooGet' token, resulting in invalid Java syntax 'ApiResponse fooGet fooGetWithHttpInfo()'. Should be 'ApiResponse fooGetWithHttpInfo()'.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3/docs/DefaultApi.md, line 73:

<comment>Documentation method signature contains extra 'fooGet' token, resulting in invalid Java syntax 'ApiResponse<FooGetDefaultResponse> fooGet fooGetWithHttpInfo()'. Should be 'ApiResponse<FooGetDefaultResponse> fooGetWithHttpInfo()'.</comment>

<file context>
@@ -0,0 +1,132 @@
+
+## fooGetWithHttpInfo
+
+> ApiResponse<FooGetDefaultResponse> fooGet fooGetWithHttpInfo()
+
+
</file context>

[robinmarechal]

Annotations are still in package com.fasterxml.annotation: https://github.com/FasterXML/jackson/wiki/Jackson-Release-3.0#annotations

I think you should remove this entire importMapping.put section

[robinmarechal]

Jackson team decided to not make a Jackson 3 version of module jackson-datatype-jsr310.
They included directly in datatabind instead.

This dependency does and will not exist for Jackson 3 (abandonned after rc2 and included directly in databind).

[robinmarechal]

Jackson 3 still uses "old" jackson-annotations module.

You need to import com.fasterxml.jackson.core:jackson-annotations, but with 2.x version

[robinmarechal]

Cf. build.gradle.mustache.

tools.jackson.core:jackson-annotations:3.x does not exist.

You should use com.fasterxml.jackson.core:jackson-annotations:2.x even for Jackson 3

[robinmarechal]

Cf. build.gradle.mustache.

jackson-datatype-jsr310 has been included directly in databind. This dependency does not exist anymore for jackson 3.

[robinmarechal]

Jackson 3 requires jdk17 or higher. Maybe we should increase this as well if useJackson3 ?

[robinmarechal]

Same as pom.xml. Jackson 3 requires jdk17 or higher. Maybe we should increase this as well if useJackson3 ?