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 (Jackson 2 stays default). When enabled, it requires Java 17+, adds a Jackson 3 sample and CI (JDK 17/21), improves RFC3339 time/error handling, and updates docs/samples after rebase.

• New Features

  • Opt-in useJackson3 for the native library: switch to tools.jackson.* imports, use JsonMapper plus Enum/DateTimeFeature, adopt SerializationContext, and update RFC3339 module/deserializers.
  • Conditional build: Jackson 3.0.4, Java 17 source/target, CI on JDK 17/21; new native-jackson3 sample; added JdkHttpClient unit test for Jackson 3.
  • Docs and samples: document useJackson3 in java/java-microprofile; fix WithHttpInfo doc signatures; regenerate Java/TypeScript samples; ensure JUnit 5 test config; minor lint/whitespace; JsonNullable works without jackson-databind-nullable.
  • Stability: catch JacksonException in API methods and oneOf/anyOf models; fix mapper.copy(); remove IOException where not thrown.
  • Dependencies: pin jackson-annotations to 2.21 for Jackson 3 builds.

• Migration

  • Default remains Jackson 2. To opt in, set additionalProperties.useJackson3=true (library=native).
  • Requires Java 17+ when using Jackson 3. Regenerate clients; no other changes needed.

^{Written for commit 786e186. 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.}

[thorstenhirsch]

I'm not sure about the JUnit 5 changes in samples/client/... - here's what Claude Sonnet 4.6 says when asked for the reason of these changes:

The sample changes come from two of our template fixes that affect all native library samples, not just the Jackson 3 one:

1. build.gradle.mustache — we added testRuntimeOnly "junit-jupiter-engine" and test { useJUnitPlatform() } to fix incomplete JUnit 5 configuration. This regenerated
   build.gradle in every native library sample (native-async, echo_api/java/native, etc.).
2. api_doc.mustache — we removed the duplicate {{operationId}} token from WithHttpInfo method signatures. This regenerated all native library API docs (removing the
   spurious prefix like > fooGet fooGetWithHttpInfo() → > fooGetWithHttpInfo()).

Sounds reasonable to me. If you don't want them here, but in a separate PR instead, I will revert them here, of course.

[thorstenhirsch]

Alright, please do another code review @cubic-dev-ai

[cubic-dev-ai]

Alright, please do another code review @cubic-dev-ai

@thorstenhirsch I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

3 issues found across 333 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="samples/client/petstore/java/native-jackson3/README.md">

<violation number="1" location="samples/client/petstore/java/native-jackson3/README.md:18">
P1: README incorrectly states Java 11+ requirement but Jackson 3 requires Java 17+. This documentation error will cause build/runtime failures for users following the instructions.</violation>
</file>

<file name="samples/client/petstore/java/native-jackson3/.travis.yml">

<violation number="1" location="samples/client/petstore/java/native-jackson3/.travis.yml:6">
P1: Travis CI uses JDK 11 (oraclejdk11) but Jackson 3.x requires Java 17+</violation>
</file>

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

<violation number="1" location="modules/openapi-generator/src/main/resources/Java/libraries/native/ApiClient.mustache:4">
P1: JsonNullableModule is not registered when useJackson3 is enabled, breaking JsonNullable (de)serialization for models generated with openApiNullable=true</violation>
</file>

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

[thorstenhirsch]

Sorry, this PR is still not ready. The generated code contains wrong imports. I'm working on it.

[thorstenhirsch]

Alright, I've fixed SerializerProvider/SerializationContext, ObjectMapper/JsonMapper issues and error handling with the new JacksonException. Now I could successfully generate a Java client with Jackson 3, all unit tests succeed. Also, I've made sure that Jackson 2 still works.

Now I guess it's finally time to start with human code reviews. And sorry @robinmarechal that I've asked you too early and wasted your time.

[wing328]

i did a test with mvn integration-test -f samples/client/petstore/java/native-jackson3/pom.xml but resulted in errors, e..g

[ERROR] /C:/Users/User/code/openapi-generator/samples/client/petstore/java/native-jackson3/src/test/java/org/openapitools/client/model/EnumTestTest.java:[21,41] package org.openapitools.jackson.nullable does not exist
[ERROR] /C:/Users/User/code/openapi-generator/samples/client/petstore/java/native-jackson3/src/test/java/org/openapitools/client/model/EnumTestTest.java:[27,41] package org.openapitools.jackson.nullable does not exist
[ERROR] /C:/Users/User/code/openapi-generator/samples/client/petstore/java/native-jackson3/src/test/java/org/openapitools/client/api/FakeApiTest.java:[320,16] cannot find symbol
[ERROR]   symbol:   class APItestGroupParametersRequest
[ERROR]   location: class org.openapitools.client.api.FakeApi
[ERROR] /C:/Users/User/code/openapi-generator/samples/client/petstore/java/native-jackson3/src/test/java/org/openapitools/client/api/FakeApiTest.java:[320,64] cannot find symbol

can you please take a look when you've time?

also please add this folder to the github workflow: https://github.com/OpenAPITools/openapi-generator/blob/master/.github/workflows/samples-java-client-jdk17.yaml