Omit the property when its value is null (default, spec-safe for non-nullable fields).
**NON_EMPTY**
Omit the property when its value is null or considered empty.
**NON_DEFAULT**
Omit the property when its value equals the default.
**NONE**
Emit no @JsonInclude annotation; defer to the global ObjectMapper.
|NON_NULL|
|parentArtifactId|parent artifactId in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effect| |null|
|parentGroupId|parent groupId in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effect| |null|
|parentVersion|parent version in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effect| |null|
@@ -153,6 +156,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|x-minimum-message|Add this property whenever you need to customize the invalidation error message for the minimum value of a variable|FIELD, OPERATION_PARAMETER|null
|x-maximum-message|Add this property whenever you need to customize the invalidation error message for the maximum value of a variable|FIELD, OPERATION_PARAMETER|null
|x-spring-api-version|Value for 'version' attribute in @RequestMapping (for Spring 7 and above).|OPERATION|null
+|x-jackson-json-include-policy|Manually override the resolved Jackson `@JsonInclude` policy for this property. Must be one of `ALWAYS`, `NON_NULL`, `NON_ABSENT`, `NON_EMPTY`, `NON_DEFAULT`, `USE_DEFAULTS`, `CUSTOM`, or `NONE` to emit no annotation. Always wins over the automatic required/nullable matrix and the `optionalNonNullPropertyJsonInclude` option.|FIELD|resolved automatically per the required/nullable matrix
## IMPORT MAPPING
diff --git a/docs/generators/kotlin-spring.md b/docs/generators/kotlin-spring.md
index f42388d53000..e821e8b34cf0 100644
--- a/docs/generators/kotlin-spring.md
+++ b/docs/generators/kotlin-spring.md
@@ -33,6 +33,8 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|documentationProvider|Select the OpenAPI documentation provider.|
**none**
Do not publish an OpenAPI specification.
**source**
Publish the original input OpenAPI specification.
**springdoc**
Generate an OpenAPI 3 specification using SpringDoc.
|springdoc|
|enumPropertyNaming|Naming convention for enum properties: 'camelCase', 'PascalCase', 'snake_case', 'UPPERCASE', 'original', and 'bestEffortBacktick' (like 'original' but tries to wrap values in backticks before falling back to sanitizing, e.g. `name,asc` stays `name,asc` rather than becoming nameCommaAsc; useful for sort/order enums)| |original|
|exceptionHandler|generate default global exception handlers (not compatible with reactive. enabling reactive will disable exceptionHandler )| |true|
+|generateJsonIncludeAnnotations|Whether to generate policy @JsonInclude annotations on model properties. When true, emits spec-honest annotations (required-field protection and the optional non-nullable policy from optionalNonNullPropertyJsonInclude). When false, none are generated and the global ObjectMapper owns inclusion. When left unset it defaults to false (7.23.0-equivalent output) and logs a warning; set it explicitly to silence the warning. A per-property override set via the `x-jackson-json-include-policy` vendor extension is always honored regardless of this flag.| |false|
+|generateJsonSetterNullsAnnotations|Whether to generate @JsonSetter(nulls = ...) annotations on optional non-nullable model properties. When true, emits @JsonSetter (Nulls.FAIL when openApiNullable is true, otherwise Nulls.SKIP) so an explicit null in the payload is handled explicitly. When false, none are generated and deserialization null-handling defers to the global ObjectMapper. When left unset it defaults to false (7.23.0-equivalent output) and logs a warning; set it explicitly to silence the warning.| |false|
|generatePageableConstraintValidation|Generate a @ValidPageable annotation and PageableConstraintValidator class, and apply @ValidPageable to the injected Pageable parameter of operations whose 'page' or 'size' parameter specifies a maximum constraint. The annotation enforces those constraints on the Pageable object that replaces the individual page/size query parameters. Requires useBeanValidation=true and library=spring-boot.| |false|
|generateSortValidation|Generate a @ValidSort annotation and SortValidator class, and apply @ValidSort to the injected Pageable parameter of operations whose 'sort' parameter has enum values. The annotation validates that sort values in the Pageable object match the allowed enum values from the spec. Requires useBeanValidation=true and library=spring-boot.| |false|
|gradleBuildFile|generate a gradle build file using the Kotlin DSL| |true|
@@ -44,6 +46,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|modelMutable|Create mutable models| |false|
|modelPackage|model package for generated code| |org.openapitools.model|
|openApiNullable|Enable OpenAPI Jackson Nullable library (jackson-databind-nullable) for strict null handling. Controls how optional + non-nullable properties (required: false, nullable: false) handle explicit JSON null: when false (default), @JsonSetter(nulls = Nulls.SKIP) is used — explicit null is silently ignored (lenient, protects any default value from being overridden); when true, @JsonSetter(nulls = Nulls.FAIL) is used — explicit null causes deserialization to fail (strict, enforces the non-nullable contract, useful for PATCH semantics). Additionally, when true, optional + nullable properties (required: false, nullable: true) use JsonNullable<T> = JsonNullable.undefined() to distinguish between a missing key and an explicit null. Requires jackson-databind-nullable >= 0.2.10 when used with useJackson3.| |false|
+|optionalNonNullPropertyJsonInclude|The Jackson @JsonInclude policy emitted for optional, non-nullable model properties when generateJsonIncludeAnnotations is true. NONE emits no annotation, deferring fully to the global ObjectMapper inclusion policy.|
**NON_NULL**
Omit the property when its value is null (default, spec-safe for non-nullable fields).
**NON_EMPTY**
Omit the property when its value is null or considered empty.
**NON_DEFAULT**
Omit the property when its value equals the default.
**NONE**
Emit no @JsonInclude annotation; defer to the global ObjectMapper.
|NON_NULL|
|packageName|Generated artifact package name.| |org.openapitools|
|parcelizeModels|toggle "@Parcelize" for generated models| |null|
|reactive|use coroutines for reactive behavior| |false|
@@ -94,6 +97,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|x-kotlin-implements|Ability to specify interfaces that model must implement|MODEL|empty array
|x-kotlin-implements-fields|Specify attributes that are implemented by the interface(s) added via `x-kotlin-implements`|MODEL|empty array
|x-spring-paginated|Add `org.springframework.data.domain.Pageable` to controller method. Can be used to handle `page`, `size` and `sort` query parameters. If these query parameters are also specified in the operation spec, they will be removed from the controller method as their values can be obtained from the `Pageable` object. Only applies when `library=spring-boot`; ignored for client libraries (spring-cloud, spring-declarative-http-interface).|OPERATION|false
+|x-jackson-json-include-policy|Manually override the resolved Jackson `@JsonInclude` policy for this property. Must be one of `ALWAYS`, `NON_NULL`, `NON_ABSENT`, `NON_EMPTY`, `NON_DEFAULT`, `USE_DEFAULTS`, `CUSTOM`, or `NONE` to emit no annotation. Always wins over the automatic required/nullable matrix and the `optionalNonNullPropertyJsonInclude` option.|FIELD|resolved automatically per the required/nullable matrix
## IMPORT MAPPING
diff --git a/docs/generators/spring.md b/docs/generators/spring.md
index 31f5f55ff4a5..f03b4183ef93 100644
--- a/docs/generators/spring.md
+++ b/docs/generators/spring.md
@@ -57,6 +57,8 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|generateBuilders|Whether to generate builders for models| |false|
|generateConstructorWithAllArgs|whether to generate a constructor for all arguments| |false|
|generateGenericResponseEntity|Use a generic type for the `ResponseEntity` wrapping return values of generated API methods. If enabled, method are generated with return type ResponseEntity<?>| |false|
+|generateJsonIncludeAnnotations|Whether to generate policy @JsonInclude annotations on model properties. When true, emits spec-honest annotations (required-field protection and the optional non-nullable policy from optionalNonNullPropertyJsonInclude). When false, none are generated and the global ObjectMapper owns inclusion. When left unset it defaults to false (7.23.0-equivalent output) and logs a warning; set it explicitly to silence the warning. A per-property override set via the `x-jackson-json-include-policy` vendor extension is always honored regardless of this flag.| |false|
+|generateJsonSetterNullsAnnotations|Whether to generate @JsonSetter(nulls = ...) annotations on optional non-nullable model properties. When true, emits @JsonSetter so an explicit null in the payload does not overwrite the field. When false, none are generated and deserialization null-handling defers to the global ObjectMapper. When left unset it defaults to false (7.23.0-equivalent output) and logs a warning; set it explicitly to silence the warning.| |false|
|generatePageableConstraintValidation|Generate a @ValidPageable annotation and PageableConstraintValidator class, and apply @ValidPageable to the injected Pageable parameter of operations whose 'page' or 'size' parameter specifies a maximum constraint. The annotation enforces those constraints on the Pageable object that replaces the individual page/size query parameters. Requires useBeanValidation=true and library=spring-boot.| |false|
|generateSortValidation|Generate a @ValidSort annotation and SortValidator class, and apply @ValidSort to the injected Pageable parameter of operations whose 'sort' parameter has enum values. The annotation validates that sort values in the Pageable object match the allowed enum values from the spec. Requires useBeanValidation=true and library=spring-boot.| |false|
|generatedConstructorWithRequiredArgs|Whether to generate constructors with required args for models| |true|
@@ -76,6 +78,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|modelPackage|package for generated models| |org.openapitools.model|
|openApiNullable|Enable OpenAPI Jackson Nullable library. Not supported by `microprofile` library.| |true|
|optionalAcceptNullable|Use `ofNullable` instead of just `of` to accept null values when using Optional.| |true|
+|optionalNonNullPropertyJsonInclude|The Jackson @JsonInclude policy emitted for optional, non-nullable model properties when generateJsonIncludeAnnotations is true. NONE emits no annotation, deferring fully to the global ObjectMapper inclusion policy.|
**NON_NULL**
Omit the property when its value is null (default, spec-safe for non-nullable fields).
**NON_EMPTY**
Omit the property when its value is null or considered empty.
**NON_DEFAULT**
Omit the property when its value equals the default.
**NONE**
Emit no @JsonInclude annotation; defer to the global ObjectMapper.
|NON_NULL|
|parentArtifactId|parent artifactId in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effect| |null|
|parentGroupId|parent groupId in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effect| |null|
|parentVersion|parent version in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effect| |null|
@@ -146,6 +149,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|x-minimum-message|Add this property whenever you need to customize the invalidation error message for the minimum value of a variable|FIELD, OPERATION_PARAMETER|null
|x-maximum-message|Add this property whenever you need to customize the invalidation error message for the maximum value of a variable|FIELD, OPERATION_PARAMETER|null
|x-spring-api-version|Value for 'version' attribute in @RequestMapping (for Spring 7 and above).|OPERATION|null
+|x-jackson-json-include-policy|Manually override the resolved Jackson `@JsonInclude` policy for this property. Must be one of `ALWAYS`, `NON_NULL`, `NON_ABSENT`, `NON_EMPTY`, `NON_DEFAULT`, `USE_DEFAULTS`, `CUSTOM`, or `NONE` to emit no annotation. Always wins over the automatic required/nullable matrix and the `optionalNonNullPropertyJsonInclude` option.|FIELD|resolved automatically per the required/nullable matrix
## IMPORT MAPPING
diff --git a/docs/migration-guide.adoc b/docs/migration-guide.adoc
index 591aebe82c91..9664005dd6a2 100644
--- a/docs/migration-guide.adoc
+++ b/docs/migration-guide.adoc
@@ -11,6 +11,43 @@ Another approach to find breaking changes is to look at issue and pull requests
* link:https://github.com/OpenAPITools/openapi-generator/labels/Breaking%20change%20%28with%20fallback%29[Breaking change (with fallback)]
* link:https://github.com/OpenAPITools/openapi-generator/labels/Breaking%20change%20%28without%20fallback%29[Breaking change (without fallback)]
+=== From 7.24.x to 7.25.0 (java-spring / kotlin-spring)
+
+Version `7.24.0` (link:https://github.com/OpenAPITools/openapi-generator/pull/23993[#23993]) started emitting field-level Jackson annotations on model properties for the `spring` and `kotlin-spring` generators:
+
+* `@JsonInclude(...)` on properties (serialization), and
+* `@JsonSetter(nulls = ...)` on optional non-nullable properties (deserialization).
+
+Field-level `@JsonInclude` overrides the project-wide `ObjectMapper` inclusion policy (for example `spring.jackson.default-property-inclusion=non_empty`), which silently changed the wire contract for projects that upgraded. See link:https://github.com/OpenAPITools/openapi-generator/issues/24401[#24401].
+
+Starting with `7.25.0`, emission of these annotations is controlled by two independent, opt-in options. When an option is left **unset**, the generator defaults to the pre-`7.24.0` (`7.23.0`) behavior — *no* annotations are emitted — and logs a warning so the choice is visible even on transitive upgrades. Set the option explicitly to silence the warning.
+
+==== Serialization: `@JsonInclude`
+
+* `generateJsonIncludeAnnotations` (boolean)
+** unset (default) → no `@JsonInclude` annotations; inclusion is governed entirely by the global `ObjectMapper` (a warning is logged).
+** `false` → same weak behavior, warning silenced.
+** `true` → emit spec-honest `@JsonInclude` annotations (required-field contract protection plus the optional non-nullable policy below).
+* `optionalNonNullPropertyJsonInclude` (enum, default `NON_NULL`) → the policy emitted for optional non-nullable properties when `generateJsonIncludeAnnotations=true`. One of `NON_NULL` / `NON_EMPTY` / `NON_DEFAULT` / `NONE` (`NONE` emits nothing).
+
+A per-property override set via the `x-jackson-json-include-policy` vendor extension always wins, regardless of these flags.
+
+==== Deserialization: `@JsonSetter(nulls = ...)`
+
+* `generateJsonSetterNullsAnnotations` (boolean)
+** unset (default) → no `@JsonSetter(nulls = ...)` annotations; null-handling is governed by the global `ObjectMapper` (a warning is logged).
+** `false` → same weak behavior, warning silenced.
+** `true` → emit `@JsonSetter(nulls = ...)` on optional non-nullable properties.
+
+[NOTE]
+====
+This also affects the `kotlin-spring` strict-null (PATCH) behavior. In `7.24.x`, an optional non-nullable property generated with `openApiNullable=true` emitted `@JsonSetter(nulls = Nulls.FAIL)`, so an explicit `null` in the payload was rejected. From `7.25.0`, that annotation is only emitted when `generateJsonSetterNullsAnnotations=true`. Leaving the option unset (or `false`) means an explicit `null` is handled by the global `ObjectMapper` instead of failing. Set `generateJsonSetterNullsAnnotations=true` to restore the strict `Nulls.FAIL` behavior.
+====
+
+==== Note
+
+`@JsonInclude(NON_ABSENT)` is no longer emitted on `JsonNullable` fields: the `JsonNullable` module already governs their inclusion, so the annotation was redundant.
+
=== From 3.x to 4.0.0
Version `4.0.0` is a major release, which contains some breaking changes without fallback.
diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/CodegenConstants.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/CodegenConstants.java
index ad507e2ff370..443acd45962d 100644
--- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/CodegenConstants.java
+++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/CodegenConstants.java
@@ -415,6 +415,12 @@ public static enum ENUM_PROPERTY_NAMING_TYPE {camelCase, PascalCase, snake_case,
public static final String USE_VERTX_5 = "useVertx5";
public static final String USE_VERTX_5_DESC = "Setting this property to true will generate Vert.x 5 specific callbacks using Callables.";
+ public static final String OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE = "optionalNonNullPropertyJsonInclude";
+
+ public static final String GENERATE_JSON_INCLUDE_ANNOTATIONS = "generateJsonIncludeAnnotations";
+
+ public static final String GENERATE_JSON_SETTER_NULLS_ANNOTATIONS = "generateJsonSetterNullsAnnotations";
+
public static final String DISALLOW_ADDITIONAL_PROPERTIES_IF_NOT_PRESENT = "disallowAdditionalPropertiesIfNotPresent";
public static final String DISALLOW_ADDITIONAL_PROPERTIES_IF_NOT_PRESENT_DESC =
"If false, the 'additionalProperties' implementation (set to true by default) is compliant with the OAS and JSON schema specifications. " +
diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/VendorExtension.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/VendorExtension.java
index 288ca9d0fb99..638bbe62b2fd 100644
--- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/VendorExtension.java
+++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/VendorExtension.java
@@ -31,7 +31,8 @@ public enum VendorExtension {
X_SIZE_MESSAGE("x-size-message", Arrays.asList(ExtensionLevel.FIELD, ExtensionLevel.OPERATION_PARAMETER), "Add this property whenever you need to customize the invalidation error message for the size or length of a variable", null),
X_MINIMUM_MESSAGE("x-minimum-message", Arrays.asList(ExtensionLevel.FIELD, ExtensionLevel.OPERATION_PARAMETER), "Add this property whenever you need to customize the invalidation error message for the minimum value of a variable", null),
X_MAXIMUM_MESSAGE("x-maximum-message", Arrays.asList(ExtensionLevel.FIELD, ExtensionLevel.OPERATION_PARAMETER), "Add this property whenever you need to customize the invalidation error message for the maximum value of a variable", null),
- X_ZERO_BASED_ENUM("x-zero-based-enum", ExtensionLevel.MODEL, "When used on an enum, the index will not be generated and the default numbering will be used, zero-based", "false");
+ X_ZERO_BASED_ENUM("x-zero-based-enum", ExtensionLevel.MODEL, "When used on an enum, the index will not be generated and the default numbering will be used, zero-based", "false"),
+ X_JACKSON_JSON_INCLUDE_POLICY("x-jackson-json-include-policy", ExtensionLevel.FIELD, "Manually override the resolved Jackson `@JsonInclude` policy for this property. Must be one of `ALWAYS`, `NON_NULL`, `NON_ABSENT`, `NON_EMPTY`, `NON_DEFAULT`, `USE_DEFAULTS`, `CUSTOM`, or `NONE` to emit no annotation. Always wins over the automatic required/nullable matrix and the `optionalNonNullPropertyJsonInclude` option.", "resolved automatically per the required/nullable matrix");
private final String name;
private final List levels;
diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java
index baaa203e60b4..66436687f4bf 100644
--- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java
+++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java
@@ -34,7 +34,10 @@
import org.openapitools.codegen.model.OperationMap;
import org.openapitools.codegen.model.OperationsMap;
import org.openapitools.codegen.templating.mustache.SpringHttpStatusLambda;
+import org.openapitools.codegen.utils.JsonAnnotationPolicyUtils;
+import org.openapitools.codegen.utils.JsonIncludePolicy;
import org.openapitools.codegen.utils.ModelUtils;
+import org.openapitools.codegen.utils.TriStateBoolean;
import org.openapitools.codegen.utils.URLPathUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@@ -184,6 +187,9 @@ public String getDescription() {
@Setter private boolean useEnumValueInterface = false;
private String valuedEnumClassName = "ValuedEnum";
@Setter private boolean suspendFunctions = false;
+ @Getter @Setter private JsonIncludePolicy optionalNonNullPropertyJsonInclude = JsonIncludePolicy.NON_NULL;
+ @Getter @Setter private TriStateBoolean generateJsonIncludeAnnotations = TriStateBoolean.UNSET;
+ @Getter @Setter private TriStateBoolean generateJsonSetterNullsAnnotations = TriStateBoolean.UNSET;
@Getter @Setter private boolean openApiNullable = false;
@Getter @Setter
protected boolean useDeductionForOneOfInterfaces = false;
@@ -315,6 +321,23 @@ public KotlinSpringServerCodegen() {
substituteGenericPagedModel);
addSwitch(COMPANION_OBJECT, "Whether to generate companion objects in data classes, enabling companion extensions.", companionObject);
addSwitch(SUSPEND_FUNCTIONS, "Whether to generate suspend functions for API operations. Useful for Spring MVC with Kotlin coroutines without requiring the full reactive stack.", suspendFunctions);
+
+ CliOption optionalNonNullPropertyJsonIncludeOpt = CliOption.newString(CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE,
+ JsonAnnotationPolicyUtils.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE_DESC);
+ for (JsonIncludePolicy policy : JsonIncludePolicy.OPTIONAL_NON_NULL_POLICIES) {
+ optionalNonNullPropertyJsonIncludeOpt.addEnum(policy.name(), policy.getDescription());
+ }
+ optionalNonNullPropertyJsonIncludeOpt.setDefault(optionalNonNullPropertyJsonInclude.name());
+ cliOptions.add(optionalNonNullPropertyJsonIncludeOpt);
+
+ addSwitch(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS,
+ JsonAnnotationPolicyUtils.GENERATE_JSON_INCLUDE_ANNOTATIONS_DESC, false);
+ addSwitch(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS,
+ "Whether to generate @JsonSetter(nulls = ...) annotations on optional non-nullable model properties. "
+ + "When true, emits @JsonSetter (Nulls.FAIL when openApiNullable is true, otherwise Nulls.SKIP) so "
+ + "an explicit null in the payload is handled explicitly. When false, none are generated and "
+ + "deserialization null-handling defers to the global ObjectMapper. When left unset it defaults to "
+ + "false (7.23.0-equivalent output) and logs a warning; set it explicitly to silence the warning.", false);
cliOptions.add(CliOption.newBoolean(CodegenConstants.USE_DEDUCTION_FOR_ONE_OF_INTERFACES, CodegenConstants.USE_DEDUCTION_FOR_ONE_OF_INTERFACES_DESC, useDeductionForOneOfInterfaces));
addSwitch(CodegenConstants.USE_ENUM_VALUE_INTERFACE, CodegenConstants.USE_ENUM_VALUE_INTERFACE_DESC, useEnumValueInterface);
addSwitch(CodegenConstants.OPENAPI_NULLABLE,
@@ -735,6 +758,19 @@ public void processOpts() {
}
writePropertyBack(SUSPEND_FUNCTIONS, suspendFunctions);
+ if (additionalProperties.containsKey(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS)) {
+ this.generateJsonIncludeAnnotations = TriStateBoolean.fromNullableBoolean(convertPropertyToBoolean(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS));
+ }
+ writePropertyBack(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, generateJsonIncludeAnnotations.isTrue());
+ if (additionalProperties.containsKey(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS)) {
+ this.generateJsonSetterNullsAnnotations = TriStateBoolean.fromNullableBoolean(convertPropertyToBoolean(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS));
+ }
+ writePropertyBack(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, generateJsonSetterNullsAnnotations.isTrue());
+ this.optionalNonNullPropertyJsonInclude = JsonAnnotationPolicyUtils.resolveOptionalNonNullPropertyJsonInclude(
+ additionalProperties, optionalNonNullPropertyJsonInclude);
+ writePropertyBack(CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE, optionalNonNullPropertyJsonInclude.name());
+ JsonAnnotationPolicyUtils.warnIfUnset(LOGGER, generateJsonIncludeAnnotations, generateJsonSetterNullsAnnotations);
+
if (additionalProperties.containsKey(BEAN_QUALIFIERS) && library.equals(SPRING_BOOT)) {
this.setBeanQualifiers(convertPropertyToBoolean(BEAN_QUALIFIERS));
}
@@ -1282,21 +1318,11 @@ public void postProcessModelProperty(CodegenModel model, CodegenProperty propert
property.example = null;
}
- // Scenario 3: optional + non-nullable → always emit @JsonSetter to handle explicit JSON nulls.
- // When openApiNullable=true: Nulls.FAIL → reject explicit null (strict PATCH semantics).
- // When openApiNullable=false: Nulls.SKIP → silently ignore explicit null (lenient, protects defaults).
- // Always emit @JsonInclude(NON_NULL) so null fields are omitted from serialized output regardless
- // of who is deserializing on the other end — closer to spec, avoids round-trip failures.
- if (!property.required && !property.isNullable) {
- if (openApiNullable) {
- property.vendorExtensions.put("x-has-json-setter-nulls-fail", true);
- } else {
- property.vendorExtensions.put("x-has-json-setter-nulls-skip", true);
- }
- model.imports.add("JsonSetter");
- model.imports.add("Nulls");
- model.imports.add("JsonInclude");
- }
+ // Emit @JsonSetter(nulls = ...) for optional, non-nullable properties when enabled; see
+ // JsonAnnotationPolicyUtils#resolveJsonSetterNullsMode for the full SKIP/FAIL rules. kotlin-spring
+ // supports both SKIP and FAIL (failModeSupported=true), unlike spring (SKIP-only).
+ applyJsonSetterNullsMode(model, property, JsonAnnotationPolicyUtils.resolveJsonSetterNullsMode(
+ generateJsonSetterNullsAnnotations, property.required, property.isNullable, openApiNullable, true));
// Scenario 4: optional + nullable with openApiNullable → use JsonNullable = JsonNullable.undefined()
// so callers can distinguish between a missing key and an explicitly provided null.
@@ -1305,6 +1331,8 @@ public void postProcessModelProperty(CodegenModel model, CodegenProperty propert
model.imports.add("JsonNullable");
}
+ resolveJsonIncludePolicy(model, property);
+
//Add imports for Jackson
if (!model.isEnum) {
model.imports.add("JsonProperty");
@@ -1324,6 +1352,32 @@ public void postProcessModelProperty(CodegenModel model, CodegenProperty propert
}
}
+ /**
+ * Apply the resolved {@code @JsonSetter(nulls = ...)} mode to a property: sets the
+ * {@code x-has-json-setter-nulls-skip}/{@code -fail} vendor extension and adds the required imports.
+ */
+ private void applyJsonSetterNullsMode(CodegenModel model, CodegenProperty property, JsonAnnotationPolicyUtils.JsonSetterNullsMode mode) {
+ if (mode == JsonAnnotationPolicyUtils.JsonSetterNullsMode.NONE) {
+ return;
+ }
+ property.vendorExtensions.put(mode == JsonAnnotationPolicyUtils.JsonSetterNullsMode.FAIL
+ ? "x-has-json-setter-nulls-fail" : "x-has-json-setter-nulls-skip", true);
+ model.imports.add("JsonSetter");
+ model.imports.add("Nulls");
+ }
+
+ /**
+ * Resolve the {@code @JsonInclude} policy into the single universal
+ * {@code x-jackson-json-include-policy} vendor extension the template emits. See
+ * {@link JsonAnnotationPolicyUtils#resolveJsonIncludePolicy} for the full precedence rules; here, required
+ * properties (nullable or not) always resolve to {@code ALWAYS} since Kotlin's non-nullable types can
+ * never hold null.
+ */
+ private void resolveJsonIncludePolicy(CodegenModel model, CodegenProperty property) {
+ JsonAnnotationPolicyUtils.resolveJsonIncludePolicy(model, property, generateJsonIncludeAnnotations,
+ optionalNonNullPropertyJsonInclude, JsonIncludePolicy.ALWAYS, JsonIncludePolicy.ALWAYS);
+ }
+
@Override
public void addImportsToOneOfInterface(List> imports) {
if (additionalProperties.containsKey("jackson")) {
@@ -1468,19 +1522,18 @@ public ModelsMap postProcessModelsEnum(ModelsMap objs) {
for (ModelMap mo : objs.getModels()) {
CodegenModel cm = mo.getModel();
for (CodegenProperty var : cm.optionalVars) {
- // Scenario 3: optional + non-nullable → always emit @JsonSetter and @JsonInclude(NON_NULL).
+ // Scenario 3: optional + non-nullable → emit @JsonSetter when generateJsonSetterNullsAnnotations is enabled.
// openApiNullable=true: Nulls.FAIL (strict). openApiNullable=false: Nulls.SKIP (lenient).
- if (!var.required && !var.isNullable) {
- if (openApiNullable) {
- var.vendorExtensions.put("x-has-json-setter-nulls-fail", true);
- } else {
- var.vendorExtensions.put("x-has-json-setter-nulls-skip", true);
- }
- }
+ applyJsonSetterNullsMode(cm, var, JsonAnnotationPolicyUtils.resolveJsonSetterNullsMode(
+ generateJsonSetterNullsAnnotations, var.required, var.isNullable, openApiNullable, true));
// Scenario 4: optional + nullable with openApiNullable → use JsonNullable
if (openApiNullable && !var.required && var.isNullable) {
var.vendorExtensions.put("x-is-jackson-optional-nullable", true);
}
+ resolveJsonIncludePolicy(cm, var);
+ }
+ for (CodegenProperty var : cm.requiredVars) {
+ resolveJsonIncludePolicy(cm, var);
}
}
@@ -1784,6 +1837,7 @@ public List getSupportedVendorExtensions() {
extensions.add(VendorExtension.X_KOTLIN_IMPLEMENTS);
extensions.add(VendorExtension.X_KOTLIN_IMPLEMENTS_FIELDS);
extensions.add(VendorExtension.X_SPRING_PAGINATED);
+ extensions.add(VendorExtension.X_JACKSON_JSON_INCLUDE_POLICY);
return extensions;
}
diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java
index 1ab10fd19d09..a449baca3e6d 100644
--- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java
+++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java
@@ -40,8 +40,11 @@
import org.openapitools.codegen.templating.mustache.SplitStringLambda;
import org.openapitools.codegen.templating.mustache.SpringHttpStatusLambda;
import org.openapitools.codegen.templating.mustache.TrimWhitespaceLambda;
+import org.openapitools.codegen.utils.JsonAnnotationPolicyUtils;
+import org.openapitools.codegen.utils.JsonIncludePolicy;
import org.openapitools.codegen.utils.ModelUtils;
import org.openapitools.codegen.utils.ProcessUtils;
+import org.openapitools.codegen.utils.TriStateBoolean;
import org.openapitools.codegen.utils.URLPathUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@@ -161,6 +164,9 @@ public enum RequestMappingMode {
@Setter protected boolean apiFirst = false;
protected boolean useOptional = false;
@Setter protected boolean useSealed = false;
+ @Getter @Setter protected JsonIncludePolicy optionalNonNullPropertyJsonInclude = JsonIncludePolicy.NON_NULL;
+ @Getter @Setter protected TriStateBoolean generateJsonIncludeAnnotations = TriStateBoolean.UNSET;
+ @Getter @Setter protected TriStateBoolean generateJsonSetterNullsAnnotations = TriStateBoolean.UNSET;
@Setter protected boolean virtualService = false;
@Setter protected boolean hateoas = false;
@Setter protected boolean returnSuccessCode = false;
@@ -284,6 +290,23 @@ public SpringCodegen() {
"Use Bean Validation Impl. to perform BeanValidation", performBeanValidation));
cliOptions.add(CliOption.newBoolean(USE_SEALED,
"Whether to generate sealed model interfaces and classes"));
+
+ CliOption optionalNonNullPropertyJsonIncludeOpt = CliOption.newString(CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE,
+ JsonAnnotationPolicyUtils.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE_DESC);
+ for (JsonIncludePolicy policy : JsonIncludePolicy.OPTIONAL_NON_NULL_POLICIES) {
+ optionalNonNullPropertyJsonIncludeOpt.addEnum(policy.name(), policy.getDescription());
+ }
+ optionalNonNullPropertyJsonIncludeOpt.setDefault(optionalNonNullPropertyJsonInclude.name());
+ cliOptions.add(optionalNonNullPropertyJsonIncludeOpt);
+
+ cliOptions.add(CliOption.newBoolean(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS,
+ JsonAnnotationPolicyUtils.GENERATE_JSON_INCLUDE_ANNOTATIONS_DESC, false));
+ cliOptions.add(CliOption.newBoolean(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS,
+ "Whether to generate @JsonSetter(nulls = ...) annotations on optional non-nullable model properties. "
+ + "When true, emits @JsonSetter so an explicit null in the payload does not overwrite the field. "
+ + "When false, none are generated and deserialization null-handling defers to the global ObjectMapper. "
+ + "When left unset it defaults to false (7.23.0-equivalent output) and logs a warning; set it "
+ + "explicitly to silence the warning.", false));
cliOptions.add(CliOption.newBoolean(API_FIRST,
"Generate the API from the OAI spec at server compile time (API first approach)", apiFirst));
cliOptions
@@ -558,6 +581,16 @@ public void processOpts() {
convertPropertyToBooleanAndWriteBack(RETURN_SUCCESS_CODE, this::setReturnSuccessCode);
convertPropertyToBooleanAndWriteBack(USE_SWAGGER_UI, this::setUseSwaggerUI);
convertPropertyToBooleanAndWriteBack(USE_SEALED, this::setUseSealed);
+ convertPropertyToBooleanAndWriteBack(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS,
+ value -> this.generateJsonIncludeAnnotations = TriStateBoolean.fromNullableBoolean(value));
+ convertPropertyToBooleanAndWriteBack(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS,
+ value -> this.generateJsonSetterNullsAnnotations = TriStateBoolean.fromNullableBoolean(value));
+ this.optionalNonNullPropertyJsonInclude = JsonAnnotationPolicyUtils.resolveOptionalNonNullPropertyJsonInclude(
+ additionalProperties, optionalNonNullPropertyJsonInclude);
+ additionalProperties.put(CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE, optionalNonNullPropertyJsonInclude.name());
+ if (jackson) {
+ JsonAnnotationPolicyUtils.warnIfUnset(LOGGER, generateJsonIncludeAnnotations, generateJsonSetterNullsAnnotations);
+ }
if (DocumentationProvider.NONE.equals(getDocumentationProvider())) {
this.setUseSwaggerUI(false);
}
@@ -1213,24 +1246,27 @@ public void postProcessModelProperty(CodegenModel model, CodegenProperty propert
model.imports.add("Arrays");
}
- // Optional + non-nullable: always emit @JsonInclude(NON_NULL) so null fields are omitted from
- // serialized output regardless of who deserializes on the other end — closer to spec.
- // When openApiNullable=false, also add @JsonSetter(nulls = Nulls.SKIP) on the setter.
- if (!property.required && !property.isNullable) {
- model.imports.add("JsonInclude");
- if (!openApiNullable) {
- property.vendorExtensions.put("x-has-json-setter-nulls-skip", true);
- model.imports.add("JsonSetter");
- model.imports.add("Nulls");
- }
- }
- // Optional + nullable with openApiNullable: emit @JsonInclude(NON_ABSENT) so that
- // JsonNullable.undefined() is excluded from serialized output.
- if (openApiNullable && !property.required && property.isNullable) {
- model.imports.add("JsonInclude");
- }
+ // Optional + non-nullable, when openApiNullable=false: add @JsonSetter(nulls = Nulls.SKIP) on the
+ // setter so an explicit null in the payload does not overwrite the field's default. Only emitted when
+ // generateJsonSetterNullsAnnotations is explicitly enabled; otherwise deserialization defers to the mapper.
+ // spring never emits Nulls.FAIL (failModeSupported=false), unlike kotlin-spring.
+ JsonAnnotationPolicyUtils.JsonSetterNullsMode jsonSetterNullsMode = JsonAnnotationPolicyUtils.resolveJsonSetterNullsMode(
+ generateJsonSetterNullsAnnotations, property.required, property.isNullable, openApiNullable, false);
+ if (jsonSetterNullsMode == JsonAnnotationPolicyUtils.JsonSetterNullsMode.SKIP) {
+ property.vendorExtensions.put("x-has-json-setter-nulls-skip", true);
+ model.imports.add("JsonSetter");
+ model.imports.add("Nulls");
+ }
+
+ // Resolve the @JsonInclude policy into the x-jackson-json-include-policy vendor extension; see
+ // JsonAnnotationPolicyUtils#resolveJsonIncludePolicy for the full precedence/matrix rules. For spring,
+ // required properties resolve to NON_NULL when non-nullable (contract protection) and ALWAYS when
+ // nullable (explicit null is valid and must be serialized).
+ JsonAnnotationPolicyUtils.resolveJsonIncludePolicy(model, property, generateJsonIncludeAnnotations,
+ optionalNonNullPropertyJsonInclude, JsonIncludePolicy.NON_NULL, JsonIncludePolicy.ALWAYS);
}
+
@Override
public CodegenModel fromModel(String name, Schema model) {
CodegenModel codegenModel = super.fromModel(name, model);
@@ -1565,6 +1601,7 @@ public List getSupportedVendorExtensions() {
extensions.add(VendorExtension.X_MINIMUM_MESSAGE);
extensions.add(VendorExtension.X_MAXIMUM_MESSAGE);
extensions.add(VendorExtension.X_SPRING_API_VERSION);
+ extensions.add(VendorExtension.X_JACKSON_JSON_INCLUDE_POLICY);
return extensions;
}
diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/JsonAnnotationPolicyUtils.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/JsonAnnotationPolicyUtils.java
new file mode 100644
index 000000000000..aae49411c61c
--- /dev/null
+++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/JsonAnnotationPolicyUtils.java
@@ -0,0 +1,247 @@
+/*
+ * Copyright 2018 OpenAPI-Generator Contributors (https://openapi-generator.tech)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.openapitools.codegen.utils;
+
+import org.openapitools.codegen.CodegenConstants;
+import org.openapitools.codegen.CodegenModel;
+import org.openapitools.codegen.CodegenProperty;
+import org.openapitools.codegen.VendorExtension;
+import org.slf4j.Logger;
+
+import java.util.Map;
+
+/**
+ * Shared resolution/validation logic for the Jackson {@code @JsonInclude}/{@code @JsonSetter(nulls = ...)}
+ * config options and the {@code x-jackson-json-include-policy} vendor extension, used by both the
+ * {@code spring} and {@code kotlin-spring} generators (issue #24401).
+ */
+public final class JsonAnnotationPolicyUtils {
+
+ /** Shared {@code CliOption} description for {@code optionalNonNullPropertyJsonInclude}. */
+ public static final String OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE_DESC =
+ "The Jackson @JsonInclude policy emitted for optional, non-nullable model properties when "
+ + CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS + " is true. "
+ + "NONE emits no annotation, deferring fully to the global ObjectMapper inclusion policy.";
+
+ /** Shared {@code CliOption} description for {@code generateJsonIncludeAnnotations}. */
+ public static final String GENERATE_JSON_INCLUDE_ANNOTATIONS_DESC =
+ "Whether to generate policy @JsonInclude annotations on model properties. When true, emits "
+ + "spec-honest annotations (required-field protection and the optional non-nullable policy from "
+ + CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE + "). When false, none are generated and the global "
+ + "ObjectMapper owns inclusion. When left unset it defaults to false (7.23.0-equivalent output) and "
+ + "logs a warning; set it explicitly to silence the warning. A per-property override set via the "
+ + "`x-jackson-json-include-policy` vendor extension is always honored regardless of this flag.";
+
+ /** Resolved {@code @JsonSetter(nulls = ...)} annotation to emit for a property, if any. */
+ public enum JsonSetterNullsMode {
+ /** No {@code @JsonSetter(nulls = ...)} annotation should be emitted. */
+ NONE,
+ /** Emit {@code @JsonSetter(nulls = Nulls.SKIP)}: silently ignore an explicit JSON null. */
+ SKIP,
+ /** Emit {@code @JsonSetter(nulls = Nulls.FAIL)}: reject an explicit JSON null. */
+ FAIL
+ }
+
+ private JsonAnnotationPolicyUtils() {
+ }
+
+ /**
+ * Validate and normalize a manual per-property {@code x-jackson-json-include-policy} override.
+ *
+ * @param rawPolicy the raw vendor extension value set directly on the property in the spec
+ * @param extensionName the vendor extension key, used in the error message (kept generator-agnostic)
+ * @return the normalized (upper-case) policy name to emit, or {@code null} when the override means
+ * "emit no annotation" ({@code NONE}/blank), in which case the caller must drop the extension.
+ * @throws IllegalArgumentException when the override is not a valid {@code JsonInclude.Include} value.
+ */
+ public static String resolveManualJsonIncludePolicy(Object rawPolicy, String extensionName) {
+ JsonIncludePolicy parsed;
+ try {
+ parsed = JsonIncludePolicy.parse(rawPolicy);
+ } catch (IllegalArgumentException e) {
+ throw new IllegalArgumentException(extensionName
+ + " must be a valid com.fasterxml.jackson.annotation.JsonInclude.Include value "
+ + "(ALWAYS, NON_NULL, NON_ABSENT, NON_EMPTY, NON_DEFAULT, USE_DEFAULTS, CUSTOM), or NONE to emit "
+ + "no annotation, but was: " + rawPolicy);
+ }
+ if (parsed == null || !parsed.isEmitted()) {
+ return null;
+ }
+ return parsed.name();
+ }
+
+ /**
+ * Validate and normalize the {@code optionalNonNullPropertyJsonInclude} config option value.
+ *
+ * @param policy the raw config option value (may be {@code null}, in which case the default
+ * {@code NON_NULL} is returned)
+ * @param optionName the config option name, used in the error message (kept generator-agnostic)
+ * @return the normalized (upper-case) policy name: one of {@code NON_NULL}, {@code NON_EMPTY},
+ * {@code NON_DEFAULT}, {@code NONE}.
+ * @throws IllegalArgumentException when the value is not one of the supported policies.
+ */
+ public static String normalizeJsonIncludePolicy(String policy, String optionName) {
+ if (policy == null) {
+ return JsonIncludePolicy.NON_NULL.name();
+ }
+ JsonIncludePolicy parsed;
+ try {
+ parsed = JsonIncludePolicy.valueOf(policy.trim().toUpperCase(java.util.Locale.ROOT));
+ } catch (IllegalArgumentException e) {
+ parsed = null;
+ }
+ if (parsed == null || !parsed.isValidOptionalNonNullPolicy()) {
+ throw new IllegalArgumentException(optionName
+ + " must be one of " + JsonIncludePolicy.OPTIONAL_NON_NULL_POLICIES + " but was: " + policy);
+ }
+ return parsed.name();
+ }
+
+ /**
+ * Read back the {@code optionalNonNullPropertyJsonInclude} config option from {@code additionalProperties},
+ * validating/normalizing it via {@link #normalizeJsonIncludePolicy}. Returns {@code current} unchanged when
+ * the option was not present in {@code additionalProperties} (i.e. the generator's existing/default value is
+ * kept). Callers are responsible for writing the resolved value back via their own
+ * {@code writePropertyBack}/{@code additionalProperties.put} convention.
+ *
+ * @param additionalProperties the generator's additional properties map
+ * @param current the generator's current {@code optionalNonNullPropertyJsonInclude} value
+ * @return the resolved {@link JsonIncludePolicy} to assign to the generator's field
+ */
+ public static JsonIncludePolicy resolveOptionalNonNullPropertyJsonInclude(Map additionalProperties, JsonIncludePolicy current) {
+ if (!additionalProperties.containsKey(CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE)) {
+ return current;
+ }
+ return JsonIncludePolicy.valueOf(normalizeJsonIncludePolicy(
+ additionalProperties.get(CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE).toString(),
+ CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE));
+ }
+
+ /**
+ * Log the shared "option left unset, defaulting to false" warnings for
+ * {@code generateJsonIncludeAnnotations}/{@code generateJsonSetterNullsAnnotations} on the caller's own
+ * {@link Logger}. No-op for each option that is not {@link TriStateBoolean#UNSET}.
+ *
+ * @param logger the calling generator's own {@code LOGGER}
+ * @param generateJsonIncludeAnnotations the resolved {@code generateJsonIncludeAnnotations} state
+ * @param generateJsonSetterNullsAnnotations the resolved {@code generateJsonSetterNullsAnnotations} state
+ */
+ public static void warnIfUnset(Logger logger, TriStateBoolean generateJsonIncludeAnnotations, TriStateBoolean generateJsonSetterNullsAnnotations) {
+ if (generateJsonIncludeAnnotations.isUnset()) {
+ logger.warn("'{}' is not set. Defaulting to false: no @JsonInclude annotations are generated and property "
+ + "inclusion is governed entirely by the global ObjectMapper (7.23.0-equivalent output). "
+ + "Set '{}=false' to keep this behavior and silence this warning, or '{}=true' to emit spec-honest "
+ + "@JsonInclude annotations (see '{}'). Note: before 7.24.0 released output had no field-level "
+ + "@JsonInclude, so leaving this unset preserves that behavior.",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS,
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE);
+ }
+ if (generateJsonSetterNullsAnnotations.isUnset()) {
+ logger.warn("'{}' is not set. Defaulting to false: no @JsonSetter(nulls = ...) annotations are generated and "
+ + "deserialization null-handling is governed entirely by the global ObjectMapper (7.23.0-equivalent "
+ + "output). Set '{}=false' to keep this behavior and silence this warning, or '{}=true' to emit "
+ + "@JsonSetter(nulls = ...) on optional non-nullable fields.",
+ CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS,
+ CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS);
+ }
+ }
+
+ /**
+ * Resolve the {@code @JsonInclude} policy into the single universal
+ * {@code x-jackson-json-include-policy} vendor extension the template emits, mutating {@code model.imports}
+ * and {@code property.vendorExtensions} in place. Precedence:
+ *
+ *
A value set directly on the property (manual override in the spec) always wins.
+ *
Otherwise, when {@code generateJsonIncludeAnnotations=true}, apply the automatic matrix:
+ *
The two "required" policies are supplied by the caller since the spring and kotlin-spring generators
+ * apply slightly different matrices there: kotlin-spring's non-nullable Kotlin types can never hold null,
+ * so it always uses {@code ALWAYS} for required properties, whereas spring uses {@code NON_NULL} for
+ * required-non-nullable (contract protection) and {@code ALWAYS} for required-nullable.
+ *
+ * @param model the model owning {@code property}, whose imports may be extended
+ * @param property the property to resolve the policy for
+ * @param generateJsonIncludeAnnotations the resolved {@code generateJsonIncludeAnnotations} state
+ * @param optionalNonNullPropertyJsonInclude the resolved {@code optionalNonNullPropertyJsonInclude} policy
+ * @param requiredNonNullablePolicy the policy to apply to required, non-nullable properties
+ * @param requiredNullablePolicy the policy to apply to required, nullable properties
+ */
+ public static void resolveJsonIncludePolicy(CodegenModel model, CodegenProperty property,
+ TriStateBoolean generateJsonIncludeAnnotations, JsonIncludePolicy optionalNonNullPropertyJsonInclude,
+ JsonIncludePolicy requiredNonNullablePolicy, JsonIncludePolicy requiredNullablePolicy) {
+ if (property.vendorExtensions.containsKey(VendorExtension.X_JACKSON_JSON_INCLUDE_POLICY.getName())) {
+ String manualPolicy = resolveManualJsonIncludePolicy(
+ property.vendorExtensions.get(VendorExtension.X_JACKSON_JSON_INCLUDE_POLICY.getName()), VendorExtension.X_JACKSON_JSON_INCLUDE_POLICY.getName());
+ if (manualPolicy != null) {
+ property.vendorExtensions.put(VendorExtension.X_JACKSON_JSON_INCLUDE_POLICY.getName(), manualPolicy);
+ model.imports.add("JsonInclude");
+ } else {
+ // NONE / empty means "emit nothing"; drop the extension so the template renders no annotation.
+ property.vendorExtensions.remove(VendorExtension.X_JACKSON_JSON_INCLUDE_POLICY.getName());
+ }
+ return;
+ }
+ if (!generateJsonIncludeAnnotations.isTrue()) {
+ return;
+ }
+ JsonIncludePolicy policy = null;
+ if (property.required) {
+ policy = property.isNullable ? requiredNullablePolicy : requiredNonNullablePolicy;
+ } else if (!property.isNullable) {
+ policy = optionalNonNullPropertyJsonInclude;
+ }
+ if (policy != null && policy.isEmitted()) {
+ property.vendorExtensions.put(VendorExtension.X_JACKSON_JSON_INCLUDE_POLICY.getName(), policy.name());
+ model.imports.add("JsonInclude");
+ }
+ }
+
+ /**
+ * Resolve which {@code @JsonSetter(nulls = ...)} annotation, if any, should be emitted for an optional,
+ * non-nullable property.
+ *
+ * @param generateJsonSetterNullsAnnotations the resolved {@code generateJsonSetterNullsAnnotations} state
+ * @param required whether the property is required
+ * @param nullable whether the property is nullable
+ * @param openApiNullable whether the generator's {@code openApiNullable} option is enabled
+ * @param failModeSupported whether this generator supports {@link JsonSetterNullsMode#FAIL} (kotlin-spring
+ * does; spring currently only ever emits {@link JsonSetterNullsMode#SKIP})
+ * @return {@link JsonSetterNullsMode#NONE} unless the property is optional and non-nullable and
+ * {@code generateJsonSetterNullsAnnotations} is explicitly enabled; otherwise {@link JsonSetterNullsMode#FAIL}
+ * when {@code openApiNullable && failModeSupported}, {@link JsonSetterNullsMode#SKIP} when
+ * {@code !openApiNullable}, or {@link JsonSetterNullsMode#NONE} when {@code openApiNullable && !failModeSupported}.
+ */
+ public static JsonSetterNullsMode resolveJsonSetterNullsMode(TriStateBoolean generateJsonSetterNullsAnnotations,
+ boolean required, boolean nullable, boolean openApiNullable, boolean failModeSupported) {
+ if (!generateJsonSetterNullsAnnotations.isTrue() || required || nullable) {
+ return JsonSetterNullsMode.NONE;
+ }
+ if (openApiNullable) {
+ return failModeSupported ? JsonSetterNullsMode.FAIL : JsonSetterNullsMode.NONE;
+ }
+ return JsonSetterNullsMode.SKIP;
+ }
+}
diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/JsonIncludePolicy.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/JsonIncludePolicy.java
new file mode 100644
index 000000000000..6c10f3f92b10
--- /dev/null
+++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/JsonIncludePolicy.java
@@ -0,0 +1,80 @@
+package org.openapitools.codegen.utils;
+
+import lombok.Getter;
+
+import java.util.EnumSet;
+import java.util.Locale;
+import java.util.Set;
+
+/**
+ * Mirrors {@code com.fasterxml.jackson.annotation.JsonInclude.Include} (the set of policies a
+ * generated {@code @JsonInclude} annotation can be given), plus a {@link #NONE} sentinel meaning
+ * "emit no {@code @JsonInclude} annotation at all", used by the {@code spring} and
+ * {@code kotlin-spring} generators (issue #24401) for:
+ *
+ *
+ *
the {@code optionalNonNullPropertyJsonInclude} config option (restricted to
+ * {@link #NON_NULL}, {@link #NON_EMPTY}, {@link #NON_DEFAULT}, {@link #NONE} — see
+ * {@link #OPTIONAL_NON_NULL_POLICIES})
+ *
the resolved {@code x-jackson-json-include-policy} vendor extension value, whether set
+ * manually on a property in the spec or computed by the automatic required/nullable matrix
+ * (any value is allowed there)
+ *
+ */
+@Getter
+public enum JsonIncludePolicy {
+ ALWAYS,
+ NON_NULL("Omit the property when its value is null (default, spec-safe for non-nullable fields)."),
+ NON_ABSENT,
+ NON_EMPTY("Omit the property when its value is null or considered empty."),
+ NON_DEFAULT("Omit the property when its value equals the default."),
+ USE_DEFAULTS,
+ CUSTOM,
+ /** Sentinel meaning "emit no {@code @JsonInclude} annotation". */
+ NONE("Emit no @JsonInclude annotation; defer to the global ObjectMapper.");
+
+ /**
+ * CLI-facing description, only populated for the values in {@link #OPTIONAL_NON_NULL_POLICIES}
+ * (the only ones ever offered as a {@code CliOption} enum choice); {@code null} otherwise.
+ */
+ private final String description;
+
+ JsonIncludePolicy() {
+ this(null);
+ }
+
+ JsonIncludePolicy(String description) {
+ this.description = description;
+ }
+
+ /** The subset of policies accepted for the {@code optionalNonNullPropertyJsonInclude} config option. */
+ public static final Set OPTIONAL_NON_NULL_POLICIES =
+ EnumSet.of(NON_NULL, NON_EMPTY, NON_DEFAULT, NONE);
+
+ /** Whether this policy should result in an emitted {@code @JsonInclude} annotation. */
+ public boolean isEmitted() {
+ return this != NONE;
+ }
+
+ /** Whether this policy is a valid value for the {@code optionalNonNullPropertyJsonInclude} config option. */
+ public boolean isValidOptionalNonNullPolicy() {
+ return OPTIONAL_NON_NULL_POLICIES.contains(this);
+ }
+
+ /**
+ * Parse a raw string (trimmed, case-insensitive) into a {@link JsonIncludePolicy}, or return
+ * {@code null} if blank/whitespace-only (callers treat that the same as {@link #NONE}).
+ *
+ * @throws IllegalArgumentException if non-blank but not a valid {@link JsonIncludePolicy} name
+ */
+ public static JsonIncludePolicy parse(Object rawPolicy) {
+ if (rawPolicy == null) {
+ return null;
+ }
+ String trimmed = rawPolicy.toString().trim();
+ if (trimmed.isEmpty()) {
+ return null;
+ }
+ return JsonIncludePolicy.valueOf(trimmed.toUpperCase(Locale.ROOT));
+ }
+}
diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/TriStateBoolean.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/TriStateBoolean.java
new file mode 100644
index 000000000000..c8a07567c0dd
--- /dev/null
+++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/TriStateBoolean.java
@@ -0,0 +1,44 @@
+package org.openapitools.codegen.utils;
+
+/**
+ * A tri-state toggle for boolean-like config options that need to distinguish "the user never set
+ * this" from an explicit {@code true}/{@code false}, e.g. so a weak default can be applied along
+ * with a one-time warning when the option was left unset, while an explicit {@code false} silently
+ * keeps the same default behavior.
+ *
+ *
This replaces the previous convention of using a boxed {@code Boolean} field where
+ * {@code null} meant "unset", which requires a code comment at every declaration site to be
+ * understandable.
+ */
+public enum TriStateBoolean {
+ /** The option was never explicitly set by the user (neither {@code true} nor {@code false}). */
+ UNSET,
+ /** The option was explicitly set to {@code false}. */
+ FALSE,
+ /** The option was explicitly set to {@code true}. */
+ TRUE;
+
+ /** Whether this state represents an explicit, affirmative opt-in ({@link #TRUE}). */
+ public boolean isTrue() {
+ return this == TRUE;
+ }
+
+ /** Whether the option was never explicitly set ({@link #UNSET}). */
+ public boolean isUnset() {
+ return this == UNSET;
+ }
+
+ /**
+ * Convert a nullable {@link Boolean} (the CLI/config-option convention where {@code null} means
+ * "not present in additionalProperties") into a {@link TriStateBoolean}.
+ *
+ * @param value {@code null} for unset, {@code Boolean.TRUE}/{@code Boolean.FALSE} for an explicit value
+ * @return {@link #UNSET}, {@link #TRUE}, or {@link #FALSE}
+ */
+ public static TriStateBoolean fromNullableBoolean(Boolean value) {
+ if (value == null) {
+ return UNSET;
+ }
+ return value ? TRUE : FALSE;
+ }
+}
diff --git a/modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache b/modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache
index 6dd2e6da00d2..b7f28efc82e9 100644
--- a/modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache
+++ b/modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache
@@ -62,14 +62,12 @@ public {{>sealed}}class {{classname}}{{#parent}} extends {{{parent}}}{{/parent}}
{{{.}}}
{{/vendorExtensions.x-field-extra-annotation}}
{{#jackson}}
- {{^required}}
- {{^isNullable}}
- @JsonInclude(JsonInclude.Include.NON_NULL)
- {{/isNullable}}
- {{/required}}
- {{#vendorExtensions.x-is-jackson-optional-nullable}}
- @JsonInclude(JsonInclude.Include.NON_ABSENT)
- {{/vendorExtensions.x-is-jackson-optional-nullable}}
+ {{#vendorExtensions.x-jackson-json-include-policy}}
+ @JsonInclude(JsonInclude.Include.{{{vendorExtensions.x-jackson-json-include-policy}}})
+ {{/vendorExtensions.x-jackson-json-include-policy}}
+ {{#vendorExtensions.x-has-json-setter-nulls-skip}}
+ @JsonSetter(nulls = Nulls.SKIP)
+ {{/vendorExtensions.x-has-json-setter-nulls-skip}}
{{/jackson}}
{{#deprecated}}
@Deprecated
@@ -252,11 +250,6 @@ public {{>sealed}}class {{classname}}{{#parent}} extends {{{parent}}}{{/parent}}
{{#vendorExtensions.x-setter-extra-annotation}}
{{{vendorExtensions.x-setter-extra-annotation}}}
{{/vendorExtensions.x-setter-extra-annotation}}
- {{#jackson}}
- {{#vendorExtensions.x-has-json-setter-nulls-skip}}
- @JsonSetter(nulls = Nulls.SKIP)
- {{/vendorExtensions.x-has-json-setter-nulls-skip}}
- {{/jackson}}
{{#deprecated}}
@Deprecated
{{/deprecated}}
diff --git a/modules/openapi-generator/src/main/resources/kotlin-spring/dataClassOptVar.mustache b/modules/openapi-generator/src/main/resources/kotlin-spring/dataClassOptVar.mustache
index 900c2e3f4662..78380ea41ac9 100644
--- a/modules/openapi-generator/src/main/resources/kotlin-spring/dataClassOptVar.mustache
+++ b/modules/openapi-generator/src/main/resources/kotlin-spring/dataClassOptVar.mustache
@@ -2,9 +2,8 @@
@Schema({{#example}}example = "{{#lambdaRemoveLineBreak}}{{#lambdaEscapeInNormalString}}{{{.}}}{{/lambdaEscapeInNormalString}}{{/lambdaRemoveLineBreak}}", {{/example}}{{#isReadOnly}}readOnly = {{{isReadOnly}}}, {{/isReadOnly}}description = "{{{description}}}"){{/swagger2AnnotationLibrary}}{{#swagger1AnnotationLibrary}}
@ApiModelProperty({{#example}}example = "{{#lambdaRemoveLineBreak}}{{#lambdaEscapeInNormalString}}{{{.}}}{{/lambdaEscapeInNormalString}}{{/lambdaRemoveLineBreak}}", {{/example}}{{#isReadOnly}}readOnly = {{{isReadOnly}}}, {{/isReadOnly}}value = "{{{description}}}"){{/swagger1AnnotationLibrary}}{{#deprecated}}
@Deprecated(message = ""){{/deprecated}}{{#vendorExtensions.x-field-extra-annotation}}
- {{{.}}}{{/vendorExtensions.x-field-extra-annotation}}{{^isNullable}}
- @field:JsonInclude(JsonInclude.Include.NON_NULL){{/isNullable}}{{#vendorExtensions.x-is-jackson-optional-nullable}}
- @field:JsonInclude(JsonInclude.Include.NON_ABSENT){{/vendorExtensions.x-is-jackson-optional-nullable}}{{#vendorExtensions.x-has-json-setter-nulls-skip}}
+ {{{.}}}{{/vendorExtensions.x-field-extra-annotation}}{{#vendorExtensions.x-jackson-json-include-policy}}
+ @field:JsonInclude(JsonInclude.Include.{{{vendorExtensions.x-jackson-json-include-policy}}}){{/vendorExtensions.x-jackson-json-include-policy}}{{#vendorExtensions.x-has-json-setter-nulls-skip}}
@field:JsonSetter(nulls = Nulls.SKIP){{/vendorExtensions.x-has-json-setter-nulls-skip}}{{#vendorExtensions.x-has-json-setter-nulls-fail}}
@field:JsonSetter(nulls = Nulls.FAIL){{/vendorExtensions.x-has-json-setter-nulls-fail}}
@param:JsonProperty("{{{baseName}}}")
diff --git a/modules/openapi-generator/src/main/resources/kotlin-spring/dataClassReqVar.mustache b/modules/openapi-generator/src/main/resources/kotlin-spring/dataClassReqVar.mustache
index 2f07705c6dd0..e299d4582a3c 100644
--- a/modules/openapi-generator/src/main/resources/kotlin-spring/dataClassReqVar.mustache
+++ b/modules/openapi-generator/src/main/resources/kotlin-spring/dataClassReqVar.mustache
@@ -1,6 +1,7 @@
{{#useBeanValidation}}{{>beanValidation}}{{>beanValidationModel}}{{/useBeanValidation}}{{#swagger2AnnotationLibrary}}
@Schema({{#example}}example = "{{#lambdaRemoveLineBreak}}{{#lambdaEscapeInNormalString}}{{{.}}}{{/lambdaEscapeInNormalString}}{{/lambdaRemoveLineBreak}}", {{/example}}required = true, {{#isReadOnly}}readOnly = {{{isReadOnly}}}, {{/isReadOnly}}description = "{{{description}}}"){{/swagger2AnnotationLibrary}}{{#swagger1AnnotationLibrary}}
@ApiModelProperty({{#example}}example = "{{#lambdaRemoveLineBreak}}{{#lambdaEscapeInNormalString}}{{{.}}}{{/lambdaEscapeInNormalString}}{{/lambdaRemoveLineBreak}}", {{/example}}required = true, {{#isReadOnly}}readOnly = {{{isReadOnly}}}, {{/isReadOnly}}value = "{{{description}}}"){{/swagger1AnnotationLibrary}}{{#vendorExtensions.x-field-extra-annotation}}
- {{{.}}}{{/vendorExtensions.x-field-extra-annotation}}
+ {{{.}}}{{/vendorExtensions.x-field-extra-annotation}}{{#vendorExtensions.x-jackson-json-include-policy}}
+ @field:JsonInclude(JsonInclude.Include.{{{vendorExtensions.x-jackson-json-include-policy}}}){{/vendorExtensions.x-jackson-json-include-policy}}
@param:JsonProperty("{{{baseName}}}")
@get:JsonProperty("{{{baseName}}}", required = true){{#isInherited}} override{{/isInherited}} {{>modelMutable}} {{{name}}}: {{#isEnum}}{{#isArray}}{{baseType}}<{{/isArray}}{{classname}}.{{{nameInPascalCase}}}{{#isArray}}>{{/isArray}}{{/isEnum}}{{^isEnum}}{{{dataType}}}{{/isEnum}}{{#isNullable}}?{{/isNullable}}{{#defaultValue}} = {{^isNumber}}{{{defaultValue}}}{{/isNumber}}{{#isNumber}}{{{dataType}}}("{{{defaultValue}}}"){{/isNumber}}{{/defaultValue}}
\ No newline at end of file
diff --git a/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java b/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java
index 2193ee5c9f9f..42ea848788da 100644
--- a/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java
+++ b/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java
@@ -8294,57 +8294,333 @@ void issue24003() throws IOException {
}
/**
- * Scenario 4 (openApiNullable=true): optional+nullable field must carry
- * {@code @JsonInclude(JsonInclude.Include.NON_ABSENT)} so that Jackson
- * excludes {@code JsonNullable.undefined()} from serialized output.
+ * Issue #24401: the {@code @JsonInclude(NON_ABSENT)} annotation must no longer be emitted for
+ * {@code JsonNullable} fields, as the JsonNullable module already governs their inclusion.
*/
@Test
- void optionalNullableField_withOpenApiNullable_hasNonAbsentAnnotation() throws IOException {
+ void optionalNullableField_withOpenApiNullable_hasNoJsonIncludeAnnotation() throws IOException {
Map files = generateFromContract(
"src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
SPRING_BOOT,
Map.of(CodegenConstants.OPENAPI_NULLABLE, "true"));
Path modelFile = files.get("TestModel.java").toPath();
- // NON_ABSENT must be present — only optionalNullable (JsonNullable) gets this annotation
- assertFileContains(modelFile, "@JsonInclude(JsonInclude.Include.NON_ABSENT)");
- // JsonNullable field must be present
- assertFileContains(modelFile, "private JsonNullable optionalNullable");
- // NON_NULL must also be present (for optionalNonNullable fields)
- assertFileContains(modelFile, "@JsonInclude(JsonInclude.Include.NON_NULL)");
- assertFileContains(modelFile, "import com.fasterxml.jackson.annotation.JsonInclude");
+ assertFileNotContains(modelFile, "@JsonInclude(JsonInclude.Include.NON_ABSENT)");
+ JavaFileAssert.assertThat(files.get("TestModel.java"))
+ .assertProperty("optionalNullable").withType("JsonNullable")
+ .assertPropertyAnnotations().doesNotContainWithName("JsonInclude");
}
/**
- * Without openApiNullable the optional+nullable field is a plain nullable type —
- * no {@code @JsonInclude(NON_ABSENT)} should be emitted.
+ * Issue #24401 (safe-but-noisy): with no flags set, the generator defaults to weak/7.23.0 behavior —
+ * NO policy {@code @JsonInclude} or {@code @JsonSetter(nulls)} annotations are emitted, deferring
+ * entirely to the global ObjectMapper.
*/
@Test
- void optionalNullableField_withoutOpenApiNullable_hasNoNonAbsentAnnotation() throws IOException {
+ void jsonInclude_unset_emitsNoPolicyAnnotations() throws IOException {
Map files = generateFromContract(
"src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
SPRING_BOOT,
- Map.of(CodegenConstants.OPENAPI_NULLABLE, "false"));
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true"));
Path modelFile = files.get("TestModel.java").toPath();
- // Without openApiNullable the field is String optionalNullable, not JsonNullable
- assertFileNotContains(modelFile, "@JsonInclude(JsonInclude.Include.NON_ABSENT)");
+ assertFileNotContains(modelFile, "@JsonInclude(");
+ assertFileNotContains(modelFile, "@JsonSetter(");
}
/**
- * Optional+non-nullable fields must still have {@code @JsonInclude(NON_NULL)} regardless
- * of the openApiNullable setting.
+ * Issue #24401: default matrix for JAVA-SPRING when {@code generateJsonIncludeAnnotations=true}
+ * (openApiNullable=true). required non-nullable -> NON_NULL, required nullable -> ALWAYS,
+ * optional non-nullable -> NON_NULL (default policy), optional nullable -> no annotation.
*/
@Test
- void optionalNonNullableField_alwaysHasNonNullAnnotation() throws IOException {
+ void jsonInclude_defaultMatrix() throws IOException {
Map files = generateFromContract(
"src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
SPRING_BOOT,
- Map.of(CodegenConstants.OPENAPI_NULLABLE, "true"));
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true"));
+
+ JavaFileAssert.assertThat(files.get("TestModel.java"))
+ .assertProperty("requiredNonNullable").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.NON_NULL")).toProperty().toType()
+ .assertProperty("requiredNullable").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.ALWAYS")).toProperty().toType()
+ .assertProperty("optionalNonNullable").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.NON_NULL")).toProperty().toType()
+ .assertProperty("optionalNullable").assertPropertyAnnotations()
+ .doesNotContainWithName("JsonInclude");
+ }
+
+ /**
+ * Issue #24401 (safe-but-noisy): {@code generateJsonSetterNullsAnnotations=true} emits
+ * {@code @JsonSetter(nulls = Nulls.SKIP)} on optional non-nullable fields (openApiNullable=false);
+ * leaving it unset emits none.
+ */
+ @Test
+ void jsonSetterNulls_generateFlag_controlsEmission() throws IOException {
+ Map withFlag = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "false",
+ CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true"));
+ assertFileContains(withFlag.get("OptionalNonNullable.java").toPath(), "@JsonSetter(nulls = Nulls.SKIP)");
+
+ Map unset = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "false"));
+ assertFileNotContains(unset.get("OptionalNonNullable.java").toPath(), "@JsonSetter(");
+ }
+
+ /**
+ * Issue #24401 regression: when Lombok generates the setter ({@code lombok.Setter}), the manual
+ * setter method (and the {@code @JsonSetter} annotation that used to live only on it) is skipped
+ * entirely. {@code @JsonSetter(nulls = Nulls.SKIP)} must be emitted on the field itself so it is
+ * still honored by Jackson even though no explicit setter method is generated.
+ */
+ @Test
+ void jsonSetterNulls_generateFlag_appliesWithLombokSetter() throws IOException {
+ Map additionalProperties = new HashMap<>();
+ additionalProperties.put(CodegenConstants.OPENAPI_NULLABLE, "false");
+ additionalProperties.put(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true");
+ additionalProperties.put(AbstractJavaCodegen.ADDITIONAL_MODEL_TYPE_ANNOTATIONS, "@lombok.Getter;@lombok.Setter");
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ additionalProperties);
+
+ JavaFileAssert.assertThat(files.get("OptionalNonNullable.java"))
+ .hasNoMethod("setOptionalNonNullable");
+ assertFileContains(files.get("OptionalNonNullable.java").toPath(), "@JsonSetter(nulls = Nulls.SKIP)");
+ }
+
+ /**
+ * Issue #24401: {@code optionalNonNullPropertyJsonInclude} changes the policy emitted for
+ * optional non-nullable properties (when {@code generateJsonIncludeAnnotations=true}).
+ */
+ @Test
+ void jsonInclude_optionalNonNullPolicy_nonEmpty() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true",
+ CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE, "NON_EMPTY"));
+
+ JavaFileAssert.assertThat(files.get("TestModel.java"))
+ .assertProperty("optionalNonNullable").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.NON_EMPTY")).toProperty().toType()
+ // required-field protection is unaffected by the optional policy
+ .assertProperty("requiredNonNullable").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.NON_NULL"));
+ }
+
+ /**
+ * Issue #24401: {@code optionalNonNullPropertyJsonInclude=NONE} emits no annotation on optional
+ * non-nullable properties, deferring to the global ObjectMapper. Required-field protection stays.
+ */
+ @Test
+ void jsonInclude_optionalNonNullPolicy_none() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true",
+ CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE, "NONE"));
+
+ JavaFileAssert.assertThat(files.get("TestModel.java"))
+ .assertProperty("optionalNonNullable").assertPropertyAnnotations()
+ .doesNotContainWithName("JsonInclude").toProperty().toType()
+ .assertProperty("requiredNonNullable").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.NON_NULL"));
+ }
+
+ /**
+ * Issue #24401: {@code generateJsonIncludeAnnotations=false} removes ALL policy @JsonInclude
+ * annotations, including the required-field protection, letting the global ObjectMapper win.
+ */
+ @Test
+ void jsonInclude_generateJsonIncludeAnnotations_false() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "false"));
Path modelFile = files.get("TestModel.java").toPath();
- assertFileContains(modelFile, "@JsonInclude(JsonInclude.Include.NON_NULL)");
- assertFileContains(modelFile, "private String optionalNonNullable");
+ assertFileNotContains(modelFile, "@JsonInclude(");
+ }
+
+ /**
+ * Issue #24401: a manual per-property {@code x-jackson-json-include-policy} vendor extension
+ * always overrides the automatic behavior, even when {@code generateJsonIncludeAnnotations=false}.
+ */
+ @Test
+ void jsonInclude_manualOverride_winsOverGenerateFlag() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_override.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "false"));
+
+ JavaFileAssert.assertThat(files.get("TestModel.java"))
+ .assertProperty("overridden").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.NON_EMPTY")).toProperty().toType()
+ // no automatic annotation on the non-overridden optional field
+ .assertProperty("plain").assertPropertyAnnotations()
+ .doesNotContainWithName("JsonInclude");
+ }
+
+ /**
+ * Issue #24401: with one property per schema, each generated model must import exactly the
+ * Jackson annotations its single property needs — no more, no less.
+ */
+ @Test
+ void jsonInclude_perSchemaImports() throws IOException {
+ final String jsonInclude = "com.fasterxml.jackson.annotation.JsonInclude";
+ final String jsonSetter = "com.fasterxml.jackson.annotation.JsonSetter";
+ final String nulls = "com.fasterxml.jackson.annotation.Nulls";
+ final String jsonNullable = "org.openapitools.jackson.nullable.JsonNullable";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true"));
+
+ // required non-nullable -> @JsonInclude(NON_NULL); no setter machinery
+ JavaFileAssert.assertThat(files.get("RequiredNonNullable.java"))
+ .hasImports(jsonInclude).hasNoImports(jsonSetter, nulls);
+ // required nullable -> @JsonInclude(ALWAYS)
+ JavaFileAssert.assertThat(files.get("RequiredNullable.java"))
+ .hasImports(jsonInclude).hasNoImports(jsonSetter, nulls);
+ // optional non-nullable with openApiNullable=true -> @JsonInclude(NON_NULL), no @JsonSetter
+ JavaFileAssert.assertThat(files.get("OptionalNonNullable.java"))
+ .hasImports(jsonInclude).hasNoImports(jsonSetter, nulls);
+ // optional nullable with openApiNullable=true -> JsonNullable, NO @JsonInclude
+ JavaFileAssert.assertThat(files.get("OptionalNullable.java"))
+ .hasImports(jsonNullable).hasNoImports(jsonInclude, jsonSetter, nulls);
+ }
+
+ /**
+ * Issue #24401: with openApiNullable=false, optional non-nullable adds @JsonSetter(Nulls.SKIP);
+ * optional nullable is a plain type needing none of the Jackson import machinery.
+ */
+ @Test
+ void jsonInclude_perSchemaImports_withoutOpenApiNullable() throws IOException {
+ final String jsonInclude = "com.fasterxml.jackson.annotation.JsonInclude";
+ final String jsonSetter = "com.fasterxml.jackson.annotation.JsonSetter";
+ final String nulls = "com.fasterxml.jackson.annotation.Nulls";
+ final String jsonNullable = "org.openapitools.jackson.nullable.JsonNullable";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "false",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true",
+ CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true"));
+
+ // optional non-nullable -> @JsonInclude(NON_NULL) + @JsonSetter(Nulls.SKIP)
+ JavaFileAssert.assertThat(files.get("OptionalNonNullable.java"))
+ .hasImports(jsonInclude, jsonSetter, nulls).hasNoImports(jsonNullable);
+ // optional nullable (plain String) -> no policy annotation, no import machinery
+ JavaFileAssert.assertThat(files.get("OptionalNullable.java"))
+ .hasNoImports(jsonInclude, jsonSetter, nulls, jsonNullable);
+ }
+
+ /**
+ * Issue #24401: even with {@code generateJsonIncludeAnnotations=false}, a manual per-property
+ * vendor extension must still emit its annotation AND the JsonInclude import must be present.
+ */
+ @Test
+ void jsonInclude_manualOverride_emitsImport_whenAnnotationsDisabled() throws IOException {
+ final String jsonInclude = "com.fasterxml.jackson.annotation.JsonInclude";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "false"));
+
+ JavaFileAssert.assertThat(files.get("ManualOverride.java"))
+ .hasImports(jsonInclude)
+ .assertProperty("value").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.NON_EMPTY"));
+ // A schema without the override must not import JsonInclude when annotations are disabled
+ JavaFileAssert.assertThat(files.get("OptionalNonNullable.java")).hasNoImports(jsonInclude);
+ }
+
+ /**
+ * Issue #24401: a forced override on an optional+nullable ({@code JsonNullable}) property must be
+ * respected — the annotation is emitted and the JsonInclude import is added, even though the
+ * automatic path emits nothing for JsonNullable fields.
+ */
+ @Test
+ void jsonInclude_forcedOverride_onJsonNullable_emitsAnnotationAndImport() throws IOException {
+ final String jsonInclude = "com.fasterxml.jackson.annotation.JsonInclude";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true"));
+
+ JavaFileAssert.assertThat(files.get("ForcedOnJsonNullable.java"))
+ .hasImports(jsonInclude)
+ .assertProperty("value").withType("JsonNullable").assertPropertyAnnotations()
+ .containsWithNameAndAttributes("JsonInclude", Map.of("value", "JsonInclude.Include.NON_NULL"));
+ }
+
+ /**
+ * Issue #24401: a manual per-property override of {@code NONE} means "emit no annotation". Neither the
+ * {@code @JsonInclude} annotation nor its import may be generated, otherwise the output fails to compile.
+ */
+ @Test
+ void jsonInclude_manualOverride_none_emitsNoAnnotationOrImport() throws IOException {
+ final String jsonInclude = "com.fasterxml.jackson.annotation.JsonInclude";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true"));
+
+ JavaFileAssert.assertThat(files.get("ManualNone.java"))
+ .hasNoImports(jsonInclude)
+ .assertProperty("value").assertPropertyAnnotations()
+ .doesNotContainWithName("JsonInclude");
+ }
+
+ /**
+ * Issue #24401: a whitespace-padded {@code NONE} override must be treated identically to a bare
+ * {@code NONE} — the sentinel comparison must trim before checking, otherwise it falls through to
+ * validation and generation fails for a value that should simply suppress the annotation.
+ */
+ @Test
+ void jsonInclude_manualOverride_paddedNone_emitsNoAnnotationOrImport() throws IOException {
+ final String jsonInclude = "com.fasterxml.jackson.annotation.JsonInclude";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true"));
+
+ JavaFileAssert.assertThat(files.get("ManualNonePadded.java"))
+ .hasNoImports(jsonInclude)
+ .assertProperty("value").assertPropertyAnnotations()
+ .doesNotContainWithName("JsonInclude");
+ }
+
+ /**
+ * Issue #24401: an invalid manual per-property override must fail fast with an actionable error
+ * during generation rather than emitting uncompilable Java.
+ */
+ @Test
+ void jsonInclude_manualOverride_invalid_failsWithActionableError() {
+ org.assertj.core.api.Assertions.assertThatThrownBy(() -> generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_invalid_override.yaml",
+ SPRING_BOOT,
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true")))
+ .hasStackTraceContaining("x-jackson-json-include-policy")
+ .hasStackTraceContaining("NOT_A_REAL_POLICY");
}
@Test
diff --git a/modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java b/modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java
index e8d9e69d1468..5f912aab61cc 100644
--- a/modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java
+++ b/modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java
@@ -6629,7 +6629,8 @@ public void requiredNullable_scenario2_requiredNullable() throws IOException {
public void requiredNullable_scenario3_optionalNonNullable() throws IOException {
Map files = generateFromContract(
"src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
- new HashMap<>());
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true",
+ CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true"));
Path modelFile = files.get("TestModel.kt").toPath();
String content = Files.readString(modelFile);
@@ -6659,7 +6660,9 @@ public void requiredNullable_scenario3_optionalNonNullable() throws IOException
public void requiredNullable_scenario3_optionalNonNullable_withOpenApiNullable() throws IOException {
Map files = generateFromContract(
"src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
- Map.of(CodegenConstants.OPENAPI_NULLABLE, "true"));
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true",
+ CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true"));
Path modelFile = files.get("TestModel.kt").toPath();
String content = Files.readString(modelFile);
@@ -6687,7 +6690,8 @@ public void requiredNullable_scenario3_optionalNonNullable_withOpenApiNullable()
public void requiredNullable_scenario3_optionalNonNullable_withDefault() throws IOException {
Map files = generateFromContract(
"src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
- new HashMap<>());
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true",
+ CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true"));
Path modelFile = files.get("TestModel.kt").toPath();
String content = Files.readString(modelFile);
@@ -6763,6 +6767,7 @@ public void requiredNullable_scenario3_optionalNonNullable_withJackson3() throws
Map props = new HashMap<>();
props.put(KotlinSpringServerCodegen.USE_SPRING_BOOT4, "true");
props.put(CodegenConstants.OPENAPI_NULLABLE, "true");
+ props.put(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true");
Map files = generateFromContract(
"src/test/resources/3_0/kotlin/required-nullable-4-states.yaml", props);
@@ -6779,28 +6784,245 @@ public void requiredNullable_scenario3_optionalNonNullable_withJackson3() throws
}
/**
- * Scenario 4 (openApiNullable=true): optional+nullable field must carry
- * {@code @field:JsonInclude(JsonInclude.Include.NON_ABSENT)} so that Jackson
- * excludes {@code JsonNullable.undefined()} from serialized output.
+ * Issue #24401: optional+nullable ({@code JsonNullable}) fields must no longer carry
+ * {@code @field:JsonInclude(NON_ABSENT)} — the JsonNullable module already governs their inclusion.
*/
- @Test(description = "Scenario 4 – optional+nullable with openApiNullable=true: @JsonInclude(NON_ABSENT) guards undefined from serialization")
- public void requiredNullable_scenario4_optionalNullable_hasNonAbsentAnnotation() throws IOException {
+ @Test(description = "Issue #24401 – optional+nullable with openApiNullable=true: no @JsonInclude annotation")
+ public void requiredNullable_scenario4_optionalNullable_hasNoJsonIncludeAnnotation() throws IOException {
Map files = generateFromContract(
"src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
Map.of(CodegenConstants.OPENAPI_NULLABLE, "true"));
Path modelFile = files.get("TestModel.kt").toPath();
- String content = Files.readString(modelFile);
- int idx = content.indexOf("val optionalNullable:");
- Assert.assertTrue(idx >= 0, "optionalNullable property must exist");
- // Annotations appear before the val declaration
- String context = content.substring(Math.max(0, idx - 300), idx);
- Assert.assertTrue(context.contains("@field:JsonInclude(JsonInclude.Include.NON_ABSENT)"),
- "optionalNullable must have @field:JsonInclude(NON_ABSENT) to suppress JsonNullable.undefined() from output");
- // Must NOT have NON_NULL — that annotation is only for non-nullable optional fields
- Assert.assertFalse(context.contains("@field:JsonInclude(JsonInclude.Include.NON_NULL)"),
- "optionalNullable must NOT have @field:JsonInclude(NON_NULL); only non-nullable optionals use NON_NULL");
- assertFileContains(modelFile, "import com.fasterxml.jackson.annotation.JsonInclude");
+ // NON_ABSENT must no longer be emitted anywhere
+ assertFileNotContains(modelFile, "@field:JsonInclude(JsonInclude.Include.NON_ABSENT)");
+ // optionalNullable must still be a JsonNullable wrapper
+ assertFileContains(modelFile, "JsonNullable");
+ }
+
+ /**
+ * Issue #24401 (safe-but-noisy): with no flags set, kotlin-spring defaults to weak/7.23.0 behavior —
+ * NO policy {@code @field:JsonInclude} or {@code @field:JsonSetter(nulls)} annotations are emitted.
+ */
+ @Test(description = "Issue #24401 – unset flags emit no policy annotations (kotlin-spring)")
+ public void jsonInclude_unset_emitsNoPolicyAnnotations() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true"));
+
+ Path modelFile = files.get("TestModel.kt").toPath();
+ assertFileNotContains(modelFile, "@field:JsonInclude(");
+ assertFileNotContains(modelFile, "@field:JsonSetter(");
+ }
+
+ /**
+ * Issue #24401: default matrix for kotlin-spring. required fields -> ALWAYS,
+ * optional non-nullable -> NON_NULL (default policy), optional nullable -> no annotation.
+ */
+ @Test(description = "Issue #24401 – default @JsonInclude matrix (kotlin-spring)")
+ public void jsonInclude_kotlinMatrix_default() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true"));
+
+ String content = Files.readString(files.get("TestModel.kt").toPath());
+ Assert.assertTrue(jsonIncludeBlockFor(content, "requiredNonNullable").contains("@field:JsonInclude(JsonInclude.Include.ALWAYS)"),
+ "required non-nullable must be ALWAYS");
+ Assert.assertTrue(jsonIncludeBlockFor(content, "requiredNullable").contains("@field:JsonInclude(JsonInclude.Include.ALWAYS)"),
+ "required nullable must be ALWAYS");
+ Assert.assertTrue(jsonIncludeBlockFor(content, "optionalNonNullable").contains("@field:JsonInclude(JsonInclude.Include.NON_NULL)"),
+ "optional non-nullable must be NON_NULL by default");
+ Assert.assertFalse(jsonIncludeBlockFor(content, "optionalNullable").contains("@field:JsonInclude"),
+ "optional nullable must have no @JsonInclude annotation");
+ }
+
+ /**
+ * Issue #24401: {@code optionalNonNullPropertyJsonInclude=NONE} omits the annotation on optional
+ * non-nullable properties while keeping the required-field protection.
+ */
+ @Test(description = "Issue #24401 – optionalNonNullPropertyJsonInclude=NONE (kotlin-spring)")
+ public void jsonInclude_optionalNonNullPolicy_none() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true",
+ CodegenConstants.OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE, "NONE"));
+
+ String content = Files.readString(files.get("TestModel.kt").toPath());
+ Assert.assertFalse(jsonIncludeBlockFor(content, "optionalNonNullable").contains("@field:JsonInclude"),
+ "optional non-nullable must have no annotation when policy is NONE");
+ Assert.assertTrue(jsonIncludeBlockFor(content, "requiredNonNullable").contains("@field:JsonInclude(JsonInclude.Include.ALWAYS)"),
+ "required-field protection must still be present");
+ }
+
+ /**
+ * Issue #24401: {@code generateJsonIncludeAnnotations=false} removes ALL policy @JsonInclude
+ * annotations, including required-field protection.
+ */
+ @Test(description = "Issue #24401 – generateJsonIncludeAnnotations=false removes all policy annotations (kotlin-spring)")
+ public void jsonInclude_generateJsonIncludeAnnotations_false() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/kotlin/required-nullable-4-states.yaml",
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "false"));
+
+ assertFileNotContains(files.get("TestModel.kt").toPath(), "@field:JsonInclude(");
+ }
+
+ /**
+ * Issue #24401: a manual per-property {@code x-jackson-json-include-policy} vendor extension always
+ * overrides the automatic behavior, even when {@code generateJsonIncludeAnnotations=false}.
+ */
+ @Test(description = "Issue #24401 – manual vendor-extension override wins (kotlin-spring)")
+ public void jsonInclude_manualOverride_winsOverGenerateFlag() throws IOException {
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_override.yaml",
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "false"));
+
+ String content = Files.readString(files.get("TestModel.kt").toPath());
+ Assert.assertTrue(jsonIncludeBlockFor(content, "overridden").contains("@field:JsonInclude(JsonInclude.Include.NON_EMPTY)"),
+ "manual override must be honored even with generateJsonIncludeAnnotations=false");
+ Assert.assertFalse(jsonIncludeBlockFor(content, "plain").contains("@field:JsonInclude"),
+ "non-overridden field must have no annotation when generateJsonIncludeAnnotations=false");
+ }
+
+ /**
+ * Returns the source region isolating a single property's annotations, bounded by the previous
+ * property's {@code @get:JsonProperty} marker, so @field:JsonInclude checks are property-specific.
+ */
+ private static String jsonIncludeBlockFor(String content, String propName) {
+ int end = content.indexOf("@get:JsonProperty(\"" + propName + "\"");
+ Assert.assertTrue(end >= 0, propName + " property must exist");
+ int prev = content.lastIndexOf("@get:JsonProperty(", end - 1);
+ return content.substring(Math.max(0, prev), end);
+ }
+
+ /**
+ * Issue #24401: with one property per schema, each generated model must import exactly the Jackson
+ * annotations its single property needs. openApiNullable=true so optional nullable uses JsonNullable.
+ */
+ @Test(description = "Issue #24401 – per-schema import isolation (kotlin-spring)")
+ public void jsonInclude_perSchemaImports() throws IOException {
+ final String jsonInclude = "import com.fasterxml.jackson.annotation.JsonInclude";
+ final String jsonSetter = "import com.fasterxml.jackson.annotation.JsonSetter";
+ final String nulls = "import com.fasterxml.jackson.annotation.Nulls";
+ final String jsonNullable = "import org.openapitools.jackson.nullable.JsonNullable";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true",
+ CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true",
+ CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true"));
+
+ // required non-nullable -> @field:JsonInclude(ALWAYS); no setter/nullable machinery
+ Path requiredNonNullable = files.get("RequiredNonNullable.kt").toPath();
+ assertFileContains(requiredNonNullable, jsonInclude);
+ assertFileNotContains(requiredNonNullable, jsonSetter, nulls, jsonNullable);
+ // required nullable -> @field:JsonInclude(ALWAYS)
+ Path requiredNullable = files.get("RequiredNullable.kt").toPath();
+ assertFileContains(requiredNullable, jsonInclude);
+ assertFileNotContains(requiredNullable, jsonSetter, nulls, jsonNullable);
+ // optional non-nullable -> @field:JsonInclude(NON_NULL) + @field:JsonSetter(Nulls.FAIL)
+ Path optionalNonNullable = files.get("OptionalNonNullable.kt").toPath();
+ assertFileContains(optionalNonNullable, jsonInclude, jsonSetter, nulls);
+ assertFileNotContains(optionalNonNullable, jsonNullable);
+ // optional nullable with openApiNullable=true -> JsonNullable, NO @field:JsonInclude
+ Path optionalNullable = files.get("OptionalNullable.kt").toPath();
+ assertFileContains(optionalNullable, jsonNullable);
+ assertFileNotContains(optionalNullable, jsonInclude, jsonSetter, nulls);
+ }
+
+ /**
+ * Issue #24401: even with {@code generateJsonIncludeAnnotations=false}, a manual per-property vendor
+ * extension must still emit its annotation AND the JsonInclude import must be present.
+ */
+ @Test(description = "Issue #24401 – manual override emits import even when annotations disabled (kotlin-spring)")
+ public void jsonInclude_manualOverride_emitsImport_whenAnnotationsDisabled() throws IOException {
+ final String jsonInclude = "import com.fasterxml.jackson.annotation.JsonInclude";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "false"));
+
+ Path manualOverride = files.get("ManualOverride.kt").toPath();
+ assertFileContains(manualOverride, jsonInclude);
+ Assert.assertTrue(jsonIncludeBlockFor(Files.readString(manualOverride), "value")
+ .contains("@field:JsonInclude(JsonInclude.Include.NON_EMPTY)"),
+ "manual override must be emitted even when generateJsonIncludeAnnotations=false");
+ // A schema without the override must not import JsonInclude when annotations are disabled
+ assertFileNotContains(files.get("OptionalNonNullable.kt").toPath(), jsonInclude);
+ }
+
+ /**
+ * Issue #24401: a forced override on an optional+nullable ({@code JsonNullable}) property must be
+ * respected — the annotation is emitted and the JsonInclude import is added.
+ */
+ @Test(description = "Issue #24401 – forced override on JsonNullable emits annotation and import (kotlin-spring)")
+ public void jsonInclude_forcedOverride_onJsonNullable_emitsAnnotationAndImport() throws IOException {
+ final String jsonInclude = "import com.fasterxml.jackson.annotation.JsonInclude";
+ final String jsonNullable = "import org.openapitools.jackson.nullable.JsonNullable";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ Map.of(CodegenConstants.OPENAPI_NULLABLE, "true"));
+
+ Path forced = files.get("ForcedOnJsonNullable.kt").toPath();
+ assertFileContains(forced, jsonInclude, jsonNullable, "JsonNullable");
+ Assert.assertTrue(jsonIncludeBlockFor(Files.readString(forced), "value")
+ .contains("@field:JsonInclude(JsonInclude.Include.NON_NULL)"),
+ "forced override on JsonNullable field must be emitted");
+ }
+
+ /**
+ * Issue #24401: a manual per-property override of {@code NONE} means "emit no annotation". Neither the
+ * {@code @field:JsonInclude} annotation nor its import may be generated, otherwise the output fails to compile.
+ */
+ @Test(description = "Issue #24401 – manual NONE override emits no annotation or import (kotlin-spring)")
+ public void jsonInclude_manualOverride_none_emitsNoAnnotationOrImport() throws IOException {
+ final String jsonInclude = "import com.fasterxml.jackson.annotation.JsonInclude";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true"));
+
+ Path manualNone = files.get("ManualNone.kt").toPath();
+ assertFileNotContains(manualNone, jsonInclude);
+ Assert.assertFalse(Files.readString(manualNone).contains("@field:JsonInclude"),
+ "manual NONE override must emit no @field:JsonInclude annotation");
+ }
+
+ /**
+ * Issue #24401: a whitespace-padded {@code NONE} override must be treated identically to a bare
+ * {@code NONE} — the sentinel comparison must trim before checking, otherwise it falls through to
+ * validation and generation fails for a value that should simply suppress the annotation.
+ */
+ @Test(description = "Issue #24401 – padded NONE override emits no annotation or import (kotlin-spring)")
+ public void jsonInclude_manualOverride_paddedNone_emitsNoAnnotationOrImport() throws IOException {
+ final String jsonInclude = "import com.fasterxml.jackson.annotation.JsonInclude";
+
+ Map files = generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml",
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true"));
+
+ Path manualNonePadded = files.get("ManualNonePadded.kt").toPath();
+ assertFileNotContains(manualNonePadded, jsonInclude);
+ Assert.assertFalse(Files.readString(manualNonePadded).contains("@field:JsonInclude"),
+ "padded NONE override must emit no @field:JsonInclude annotation");
+ }
+
+ /**
+ * Issue #24401: an invalid manual per-property override must fail fast with an actionable error
+ * during generation rather than emitting uncompilable Kotlin.
+ */
+ @Test(description = "Issue #24401 – invalid manual override fails fast (kotlin-spring)")
+ public void jsonInclude_manualOverride_invalid_failsWithActionableError() {
+ Throwable thrown = Assert.expectThrows(Throwable.class, () -> generateFromContract(
+ "src/test/resources/3_0/spring/issue_24401_json_include_invalid_override.yaml",
+ Map.of(CodegenConstants.GENERATE_JSON_INCLUDE_ANNOTATIONS, "true")));
+
+ java.io.StringWriter sw = new java.io.StringWriter();
+ thrown.printStackTrace(new java.io.PrintWriter(sw));
+ String trace = sw.toString();
+ Assert.assertTrue(trace.contains("x-jackson-json-include-policy") && trace.contains("NOT_A_REAL_POLICY"),
+ "expected an actionable error naming the invalid policy, but got: " + trace);
}
/**
@@ -7087,6 +7309,7 @@ public void testIssue24139NullableRefNoJsonSetterNullsFail() throws IOException
Map additionalProperties = new HashMap<>();
additionalProperties.put("useBeanValidation", true);
additionalProperties.put("openApiNullable", "true");
+ additionalProperties.put(CodegenConstants.GENERATE_JSON_SETTER_NULLS_ANNOTATIONS, "true");
Map files = generateFromContract(
"src/test/resources/3_1/issue_24139.yaml",
diff --git a/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_invalid_override.yaml b/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_invalid_override.yaml
new file mode 100644
index 000000000000..39d6b3ed12eb
--- /dev/null
+++ b/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_invalid_override.yaml
@@ -0,0 +1,28 @@
+openapi: 3.0.0
+info:
+ title: JsonInclude invalid manual override test
+ version: 1.0.0
+ description: >
+ A single schema whose property carries an invalid x-jackson-json-include-policy value.
+ Generation must fail fast with an actionable error rather than emitting uncompilable output.
+paths:
+ /test:
+ post:
+ operationId: testPost
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/InvalidOverride'
+ responses:
+ '200':
+ description: OK
+components:
+ schemas:
+ InvalidOverride:
+ type: object
+ properties:
+ value:
+ type: string
+ nullable: false
+ x-jackson-json-include-policy: NOT_A_REAL_POLICY
diff --git a/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_override.yaml b/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_override.yaml
new file mode 100644
index 000000000000..c39028982365
--- /dev/null
+++ b/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_override.yaml
@@ -0,0 +1,30 @@
+openapi: 3.0.0
+info:
+ title: JsonInclude manual override test
+ version: 1.0.0
+paths:
+ /test:
+ post:
+ operationId: testPost
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TestModel'
+ responses:
+ '200':
+ description: OK
+components:
+ schemas:
+ TestModel:
+ type: object
+ properties:
+ # Manual per-property override via the universal vendor extension.
+ overridden:
+ type: string
+ nullable: false
+ x-jackson-json-include-policy: NON_EMPTY
+ # No override: with generateJsonIncludeAnnotations=false this must get no annotation.
+ plain:
+ type: string
+ nullable: false
diff --git a/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml b/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml
new file mode 100644
index 000000000000..5e10c8cf438e
--- /dev/null
+++ b/modules/openapi-generator/src/test/resources/3_0/spring/issue_24401_json_include_per_schema.yaml
@@ -0,0 +1,99 @@
+openapi: 3.0.0
+info:
+ title: JsonInclude per-schema import isolation test
+ version: 1.0.0
+ description: >
+ Each schema holds exactly one property covering one required/optional x
+ nullable/non-nullable combination. Isolating a single case per model ensures the
+ generated imports (JsonInclude, JsonSetter, Nulls, JsonNullable) are correct for
+ every case on their own, without another property masking a missing import.
+paths:
+ /test:
+ post:
+ operationId: testPost
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RequiredNonNullable'
+ responses:
+ '200':
+ description: OK
+components:
+ schemas:
+ # required + non-nullable
+ RequiredNonNullable:
+ type: object
+ required:
+ - value
+ properties:
+ value:
+ type: string
+ nullable: false
+ # required + nullable
+ RequiredNullable:
+ type: object
+ required:
+ - value
+ properties:
+ value:
+ type: string
+ nullable: true
+ # optional + non-nullable
+ OptionalNonNullable:
+ type: object
+ properties:
+ value:
+ type: string
+ nullable: false
+ # optional + non-nullable with a default value
+ OptionalNonNullableWithDefault:
+ type: object
+ properties:
+ value:
+ type: string
+ nullable: false
+ default: "defaultValue"
+ # optional + nullable
+ OptionalNullable:
+ type: object
+ properties:
+ value:
+ type: string
+ nullable: true
+ # manual per-property override: even with generateJsonIncludeAnnotations=false the
+ # annotation (and its import) must still be emitted from the vendor extension.
+ ManualOverride:
+ type: object
+ properties:
+ value:
+ type: string
+ nullable: false
+ x-jackson-json-include-policy: NON_EMPTY
+ # forced override on an optional + nullable (JsonNullable) property: the automatic path emits
+ # nothing here, but an explicit vendor extension must be respected and its import added.
+ ForcedOnJsonNullable:
+ type: object
+ properties:
+ value:
+ type: string
+ nullable: true
+ x-jackson-json-include-policy: NON_NULL
+ # manual per-property override of NONE: the sentinel means "emit no annotation", so neither the
+ # @JsonInclude annotation nor its import must be generated (otherwise the output fails to compile).
+ ManualNone:
+ type: object
+ properties:
+ value:
+ type: string
+ nullable: false
+ x-jackson-json-include-policy: NONE
+ # manual per-property override of NONE padded with whitespace: must be treated identically to a
+ # bare NONE (normalization must trim before comparing), i.e. emit no annotation, no validation error.
+ ManualNonePadded:
+ type: object
+ properties:
+ value:
+ type: string
+ nullable: false
+ x-jackson-json-include-policy: " NONE "
diff --git a/samples/client/petstore/spring-cloud-date-time/src/main/java/org/openapitools/model/Pet.java b/samples/client/petstore/spring-cloud-date-time/src/main/java/org/openapitools/model/Pet.java
index 4aa4e0f36117..83c89d9c9800 100644
--- a/samples/client/petstore/spring-cloud-date-time/src/main/java/org/openapitools/model/Pet.java
+++ b/samples/client/petstore/spring-cloud-date-time/src/main/java/org/openapitools/model/Pet.java
@@ -29,6 +29,7 @@
@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", comments = "Generator version: 7.25.0-SNAPSHOT")
public class Pet {
+ @JsonInclude(JsonInclude.Include.NON_NULL)
private String atType = "Pet";
@JsonInclude(JsonInclude.Include.NON_NULL)
diff --git a/samples/client/petstore/spring-cloud-deprecated/src/main/java/org/openapitools/model/Pet.java b/samples/client/petstore/spring-cloud-deprecated/src/main/java/org/openapitools/model/Pet.java
index 0d9d99f20e09..53b64044c6e3 100644
--- a/samples/client/petstore/spring-cloud-deprecated/src/main/java/org/openapitools/model/Pet.java
+++ b/samples/client/petstore/spring-cloud-deprecated/src/main/java/org/openapitools/model/Pet.java
@@ -36,8 +36,10 @@ public class Pet {
@JsonInclude(JsonInclude.Include.NON_NULL)
private @Nullable Category category;
+ @JsonInclude(JsonInclude.Include.ALWAYS)
private JsonNullable name = JsonNullable.undefined();
+ @JsonInclude(JsonInclude.Include.NON_NULL)
@Deprecated
private List photoUrls = new ArrayList<>();
diff --git a/samples/client/petstore/spring-cloud-feign-without-url/src/main/java/org/openapitools/model/Pet.java b/samples/client/petstore/spring-cloud-feign-without-url/src/main/java/org/openapitools/model/Pet.java
index 37d29c32b8da..c16ac8affc4e 100644
--- a/samples/client/petstore/spring-cloud-feign-without-url/src/main/java/org/openapitools/model/Pet.java
+++ b/samples/client/petstore/spring-cloud-feign-without-url/src/main/java/org/openapitools/model/Pet.java
@@ -36,8 +36,10 @@ public class Pet {
@JsonInclude(JsonInclude.Include.NON_NULL)
private @Nullable Category category;
+ @JsonInclude(JsonInclude.Include.NON_NULL)
private String name;
+ @JsonInclude(JsonInclude.Include.NON_NULL)
private List photoUrls = new ArrayList<>();
@JsonInclude(JsonInclude.Include.NON_NULL)
diff --git a/samples/client/petstore/spring-cloud-tags/src/main/java/org/openapitools/model/Pet.java b/samples/client/petstore/spring-cloud-tags/src/main/java/org/openapitools/model/Pet.java
index f655d26b20a7..141ad532407c 100644
--- a/samples/client/petstore/spring-cloud-tags/src/main/java/org/openapitools/model/Pet.java
+++ b/samples/client/petstore/spring-cloud-tags/src/main/java/org/openapitools/model/Pet.java
@@ -36,8 +36,10 @@ public class Pet {
@JsonInclude(JsonInclude.Include.NON_NULL)
private @Nullable Category category;
+ @JsonInclude(JsonInclude.Include.NON_NULL)
private String name;
+ @JsonInclude(JsonInclude.Include.NON_NULL)
private List photoUrls = new ArrayList<>();
@JsonInclude(JsonInclude.Include.NON_NULL)
diff --git a/samples/client/petstore/spring-cloud/src/main/java/org/openapitools/model/Pet.java b/samples/client/petstore/spring-cloud/src/main/java/org/openapitools/model/Pet.java
index 37d29c32b8da..c16ac8affc4e 100644
--- a/samples/client/petstore/spring-cloud/src/main/java/org/openapitools/model/Pet.java
+++ b/samples/client/petstore/spring-cloud/src/main/java/org/openapitools/model/Pet.java
@@ -36,8 +36,10 @@ public class Pet {
@JsonInclude(JsonInclude.Include.NON_NULL)
private @Nullable Category category;
+ @JsonInclude(JsonInclude.Include.NON_NULL)
private String name;
+ @JsonInclude(JsonInclude.Include.NON_NULL)
private List photoUrls = new ArrayList<>();
@JsonInclude(JsonInclude.Include.NON_NULL)
diff --git a/samples/client/petstore/spring-http-interface-bean-validation/src/main/java/org/openapitools/model/AdditionalPropertiesClassDto.java b/samples/client/petstore/spring-http-interface-bean-validation/src/main/java/org/openapitools/model/AdditionalPropertiesClassDto.java
index 46a16d7fe21d..fb95071ae45f 100644
--- a/samples/client/petstore/spring-http-interface-bean-validation/src/main/java/org/openapitools/model/AdditionalPropertiesClassDto.java
+++ b/samples/client/petstore/spring-http-interface-bean-validation/src/main/java/org/openapitools/model/AdditionalPropertiesClassDto.java
@@ -58,7 +58,6 @@ public class AdditionalPropertiesClassDto {
@JsonInclude(JsonInclude.Include.NON_NULL)
private @Nullable Object anytype1;
- @JsonInclude(JsonInclude.Include.NON_ABSENT)
private JsonNullable