Feature/fix json include

docs/migration-guide.adoc

@@ -11,6 +11,38 @@ 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
+
+`@JsonInclude(NON_ABSENT)` is no longer emitted on `JsonNullable<T>` 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.

modules/openapi-generator/src/main/java/org/openapitools/codegen/CodegenConstants.java

@@ -415,6 +415,15 @@ 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 OPTIONAL_NON_NULL_PROPERTY_JSON_INCLUDE_DESC = "The Jackson @JsonInclude policy to apply to optional, non-nullable properties (ignored unless generateJsonIncludeAnnotations is true).";
+
+    public static final String GENERATE_JSON_INCLUDE_ANNOTATIONS = "generateJsonIncludeAnnotations";
+    public static final String GENERATE_JSON_INCLUDE_ANNOTATIONS_DESC = "Generate field-level @JsonInclude annotations controlling Jackson serialization inclusion. When unset or false, no @JsonInclude annotations are generated and the project-wide ObjectMapper policy applies.";
+
+    public static final String GENERATE_JSON_SETTER_NULLS_ANNOTATIONS = "generateJsonSetterNullsAnnotations";
+    public static final String GENERATE_JSON_SETTER_NULLS_ANNOTATIONS_DESC = "Generate field-level @JsonSetter(nulls = ...) annotations controlling Jackson deserialization null-handling for optional, non-nullable properties. When unset or false, no @JsonSetter annotations are generated and the project-wide ObjectMapper policy applies.";
+
     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. " +

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<ExtensionLevel> levels;