feature/jackson3 native (fixes #22294) by thorstenhirsch · Pull Request #23071 · OpenAPITools/openapi-generator

thorstenhirsch · 2026-02-27T17:21:45Z

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 while keeping Jackson 2 as default. When enabled, it requires Java 17+, improves RFC3339 date/time handling, and ships a native-jackson3 sample with CI (JDK 17/21).

New Features
- Opt-in useJackson3: dynamic imports via {{jacksonPackage}}; switch to JsonMapper with EnumFeature/DateTimeFeature; adopt SerializationContext; update RFC3339 module/Instant deserializer; better anyOf/oneOf; handle JacksonException; remove unused IOException; fix mapper.copy().
- Build/CI: Java 17 source/target for Jackson 3; upgrade to Jackson 3.1.0; pin jackson-annotations 2.21; add native-jackson3 sample and include it in JDK 17/21 CI; add JDK HttpClient test; enable JUnit 5 in native/native-async Gradle builds.
- Docs and samples: document useJackson3 for 'native' and 'restclient' (requires useSpringBoot4=true); clarify 'openApiNullable' incompatibility and note it auto-disables when both are set; fix WithHttpInfo doc signatures; regenerate Java/TypeScript samples; JsonNullable works without jackson-databind-nullable.
Migration
- Default remains Jackson 2. To opt in for 'native', set additionalProperties.useJackson3=true.
- Requires Java 17+ when using Jackson 3. Regenerate clients; no other changes needed.

^{Written for commit 4ce631a. 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.}

modules/openapi-generator/src/main/resources/Java/libraries/native/model.mustache

modules/openapi-generator/src/main/resources/Java/libraries/native/pom.mustache

samples/client/petstore/java/native-jackson3/build.gradle

samples/client/petstore/java/native-jackson3/docs/DefaultApi.md

...es/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaClientCodegen.java

modules/openapi-generator/src/main/resources/Java/libraries/native/build.gradle.mustache

modules/openapi-generator/src/main/resources/Java/libraries/native/pom.mustache

modules/openapi-generator/src/main/resources/Java/libraries/native/build.gradle.mustache

thorstenhirsch · 2026-03-01T18:23:18Z

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:

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.).

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 · 2026-03-01T18:43:05Z

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

cubic-dev-ai · 2026-03-01T18:43:12Z

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.}

samples/client/petstore/java/native-jackson3/README.md

samples/client/petstore/java/native-jackson3/.travis.yml

modules/openapi-generator/src/main/resources/Java/libraries/native/ApiClient.mustache

…on-databind-nullable

thorstenhirsch · 2026-03-03T10:27:40Z

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

thorstenhirsch · 2026-03-03T16:29:04Z

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 · 2026-03-04T03:07:03Z

bin/configs/java-native-jackson3.yaml

@@ -0,0 +1,11 @@
+generatorName: java
+outputDir: samples/client/petstore/java/native-jackson3


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

thorstenhirsch · 2026-03-04T22:07:01Z

Lots of getters and setters missing in modules/openapi-generator/src/main/java/org/openapitools/codegen/CodegenModel.java after I've merged master into this feature branch. Looks like I now need to respect useSpringBoot4, as well. Let me give it a shot ...

cubic-dev-ai

1 issue found across 66 files (changes from recent commits).

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="docs/generators/java.md">

<violation number="1" location="docs/generators/java.md:100">
P2: Documentation for useJackson3 with 'native' library is missing Java 17 requirement. Jackson 3 requires Java 17 but the documentation only mentions 'native' library requires Java 11+, misleading users who may attempt to use useJackson3 on Java 11-16.</violation>
</file>

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

docs/generators/java.md

thorstenhirsch · 2026-03-04T23:03:35Z

Alright, this branch is now aligned with restclient's Jackson 3.1.0, unit tests and the integration test you mentioned succeed. @wing328

docs/generators/java-microprofile.md

Clarify the incompatibility of Jackson 3 with openApiNullable in the documentation.

cubic-dev-ai

1 issue found across 1 file (changes from recent commits).

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="docs/generators/java-microprofile.md">

<violation number="1" location="docs/generators/java-microprofile.md:100">
P2: Documentation regression: The `useJackson3` option description removes the incompatibility warning for `openApiNullable`, but the generator code (`JavaClientCodegen.java`) still silently disables `openApiNullable` when both options are enabled. This creates a documentation-to-implementation contract mismatch where users expect the combination to work but won't get the expected nullable functionality in generated code.</violation>
</file>

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

docs/generators/java-microprofile.md

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

robinmarechal · 2026-03-06T17:01:14Z

tools/jackson/databind/cfg/DateTimeFeature.class

Was this file pushed by error?

robinmarechal · 2026-03-06T17:07:30Z

...es/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaClientCodegen.java

        cliOptions.add(CliOption.newBoolean(SUPPORT_URL_QUERY, "Generate toUrlQueryString in POJO (default to true). Available on `native`, `apache-httpclient` libraries."));
        cliOptions.add(CliOption.newBoolean(USE_ENUM_CASE_INSENSITIVE, "Use `equalsIgnoreCase` when String for enum comparison", useEnumCaseInsensitive));
        cliOptions.add(CliOption.newBoolean(FAIL_ON_UNKNOWN_PROPERTIES, "Fail Jackson de-serialization on unknown properties", this.failOnUnknownProperties));
+        cliOptions.add(CliOption.newBoolean(USE_JACKSON_3, "Use Jackson 3 instead of Jackson 2. Supported for 'native' library (requires Java 17+) and for 'restclient' library (requires useSpringBoot4=true).", this.useJackson3));


A PR implementing useJackson3 for restclient has already been merged to master. cf. #23023.
These attributes, cliOptions, etc... already exists in master.

I think you should update your branch ans use what already exists 🙂

robinmarechal · 2026-03-06T17:15:49Z

...es/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaClientCodegen.java

+        if (useJackson3 && libRestClient && !useSpringBoot4) {
+            throw new IllegalArgumentException("useJackson3 for the restclient library requires useSpringBoot4=true");
+        } else if (useJackson3 && !libNative && !libRestClient) {
+            LOGGER.warn("useJackson3 is only supported for 'native' and 'restclient' libraries. Disabling useJackson3.");


I think silently disabling a feature is not the right thing to do (even if its logged as a warning, one warning in thousands of lines can be almost invisible).

I'd personnally prefer that the generation fails with a clear error message, telling my to explicitly set an option in my config, instead of an unexpected behavior because i didn't see this specific warning.

And that's what has been done for openApiNullable in #23023 which has already been merged

thorstenhirsch added 2 commits February 27, 2026 14:04

add jackson 3 support to java native

2a9e1e6

upgrade to jackson 3.0.4, fix whitespaces

8f7a982

thorstenhirsch mentioned this pull request Feb 27, 2026

[REQ] Jackson3 support for java libraries #22294

Open

thorstenhirsch marked this pull request as ready for review February 27, 2026 17:39

cubic-dev-ai bot reviewed Feb 27, 2026

View reviewed changes

robinmarechal mentioned this pull request Feb 28, 2026

[java][webclient] Jackson3 support for webclient robinmarechal/openapi-generator#1

Closed

6 tasks

robinmarechal suggested changes Feb 28, 2026

View reviewed changes

...es/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaClientCodegen.java Outdated Show resolved Hide resolved

robinmarechal mentioned this pull request Feb 28, 2026

[java][webclient] Jackson3 support for webclient #23072

Open

6 tasks

robinmarechal suggested changes Feb 28, 2026

View reviewed changes

thorstenhirsch added 3 commits March 1, 2026 12:31

remove importMapping.put section

a8fb300

require Java 17 for Jackson 3

b69df0d

fix cubic-dev-ai issues, fix unit tests

caca305

cubic-dev-ai bot reviewed Mar 1, 2026

View reviewed changes

fix more cubic-dev-ai findings, includes a solution for missing jacks…

4e39fad

…on-databind-nullable

thorstenhirsch requested a review from robinmarechal March 1, 2026 19:52

thorstenhirsch added 7 commits March 3, 2026 12:54

use SerializationContext instead of SerializerProvider

f13f114

use JsonMapper instead of ObjectMapper for Jackson 3

a1e24d1

also fix Mapper in JSON.java for Jackson 3

e8453d3

update samples

fd4a67c

fix mapper.copy()

19d1296

add JacksonException handling

f118f3f

remove IOException where not thrown anymore

8091162

thorstenhirsch added 3 commits March 3, 2026 22:28

Merge branch 'master' into feature/jackson3-native

45dc531

Update jackson_annotations_version in build.gradle.mustache

bf23069

update samples after rebase

786e186

wing328 added Client: Java Enhancement: Feature labels Mar 4, 2026

wing328 added this to the 7.21.0 milestone Mar 4, 2026

wing328 reviewed Mar 4, 2026

View reviewed changes

thorstenhirsch added 3 commits March 4, 2026 22:38

fix FakeApi integration test

d4bcb59

add native-jackson3 to samples-java-client-jdk17 workflow

9d5e569

Merge branch 'master' into feature/jackson3-native

3bc4c27

thorstenhirsch added 2 commits March 4, 2026 23:14

fix compile errors

fbf011e

update samples and docs

52a5a6b

cubic-dev-ai bot reviewed Mar 4, 2026

View reviewed changes

docs/generators/java.md Outdated Show resolved Hide resolved

thorstenhirsch added 2 commits March 4, 2026 23:46

update Jackson to v3.1.0, use {{jacksonPackage}}

cf4a519

update docs and samples

5d2fb18

wing328 reviewed Mar 5, 2026

View reviewed changes

docs/generators/java-microprofile.md Outdated Show resolved Hide resolved

thorstenhirsch added 3 commits March 5, 2026 22:00

Update Jackson 3 compatibility note in documentation

c93e857

Clarify the incompatibility of Jackson 3 with openApiNullable in the documentation.

Merge branch 'OpenAPITools:master' into feature/jackson3-native

b0f9078

update the correct documentation

e801e42

cubic-dev-ai bot reviewed Mar 5, 2026

View reviewed changes

docs/generators/java-microprofile.md Outdated Show resolved Hide resolved

Update docs/generators/java-microprofile.md once again

4ce631a

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

robinmarechal suggested changes Mar 6, 2026

View reviewed changes

		@@ -0,0 +1,11 @@
		generatorName: java
		outputDir: samples/client/petstore/java/native-jackson3

Uh oh!

Conversation

thorstenhirsch commented Feb 27, 2026 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR checklist

Summary by cubic

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thorstenhirsch commented Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thorstenhirsch commented Mar 1, 2026

Uh oh!

cubic-dev-ai bot commented Mar 1, 2026

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thorstenhirsch commented Mar 3, 2026

Uh oh!

thorstenhirsch commented Mar 3, 2026

Uh oh!

wing328 Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

thorstenhirsch commented Mar 4, 2026

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thorstenhirsch commented Mar 4, 2026

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

robinmarechal Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

robinmarechal Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

robinmarechal Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

thorstenhirsch commented Feb 27, 2026 •

edited by cubic-dev-ai bot

Loading

thorstenhirsch commented Mar 1, 2026 •

edited

Loading