[java][native] add generateJsonCreator to distinguish between oneOf types w/o discriminator
This PR fixes https://github.com/OpenAPITools/openapi-generator/issues/25727. Besides the example in the issue I've also tested the fix successfully against a real-world openapi spec that triggered the problem.
This PR introduces a new additional property generateJsonCreator, which is false by default, because I do not dare to change the default behavior. When set to true it will add @JsonCreator constructor code for the parser to check for required properties, especially to distinguish between multiple types in an oneOf array. Actually, this might be what most people expect: a parser should fail when trying to parse a type in a oneOf array and the input does not contain the properties that are listed in the required array of said type. Unfortunately, this is not the case (at least not when unknown properties are ignored, which is the default behavior). Instead, the parser is happy with all possible types in the oneOf array and fails with this error:
Failed deserialization for Author: 2 classes match result, expected 1
So, with this PR this problem is being resolved, only 1 class will match - as long as the required fields differ between the possible oneOf types, which is probably the case in most openapi specs that don't come with a discriminator.
Please feel free not only to approve this PR, but also to change the default behavior to generateJsonCreator=true, as this is probably the expected behavior of most users.
PR checklist
- Read the contribution guidelines.
- Run the following to build the project and update samples:
(For Windows users, please run the script in WSL)./mvnw clean package || exit ./bin/generate-samples.sh ./bin/configs/*.yaml || exit ./bin/utils/export_docs_generators.sh || exit
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. - 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) @KannaKim (2026/07) @AndreyVMarkelov (2026/11)
Summary by cubic
Fixes #25727 by adding an opt-in generateJsonCreator option for the Java native library so oneOf variants without a discriminator no longer deserialize into multiple classes.
Adds a @JsonCreator constructor holding required and read-only properties to generated models, making deserialization fail when a required property is missing. This is needed when Jackson is configured to ignore unknown properties—without the creator, every variant in a oneOf array matches and the parser errors with "2 classes match result, expected 1". The option is off by default. Models that override an inherited property with an incompatible type fall back to the no-arg constructor.
Bug Fixes
- Required nullable properties stay required, since the value may be null but the property must still be present to distinguish
oneOfvariants. - Uses the
jacksonPackagevalue for XML annotation imports so Jackson 3 resolvestools.jackson.dataformatcorrectly. - Adds missing XML processing and JAXB dependencies to the native
build.gradleandpom.xmltemplates forwithXmlbuilds.
New Features
- Adds
generateJsonCreatorconfiguration option (native library only, Jackson 2 and 3). - Generates
@JsonCreator(mode = PROPERTIES)constructors that chain to parent constructors for inherited required properties.