OpenAPI Generator 升级到 7.25 后 Jackson 注解（@JsonInclude/@JsonSetter）行为变化怎么处理？-平芜编程栈

OpenAPI Generator 升级到 7.25 后 Jackson 注解（@JsonInclude/@JsonSetter）行为变化怎么处理？

【免费下载链接】openapi-generatorOpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)项目地址: https://gitcode.com/GitHub_Trending/op/openapi-generator

如果你用 OpenAPI Generator 的spring或kotlin-spring生成器产出模型代码，把生成器版本升到7.25.0后需要回答一个问题：模型属性上的 Jackson 注解要保留还是去掉。背景是这样的：7.24.0开始，这两个生成器会在模型属性上输出字段级注解——用于序列化的@JsonInclude(...)，以及用于反序列化、针对 optional 且非 nullable 属性的@JsonSetter(nulls = ...)（见迁移指南）。字段级@JsonInclude会覆盖项目全局的ObjectMapperinclusion 策略（例如spring.jackson.default-property-inclusion=non_empty），导致升级项目的 wire 契约被静默改变。

从7.25.0起，这些注解的输出改由两个独立的 opt-in 选项控制。选项不设置时，生成器回退到7.24.0之前（即7.23.0）的行为——不输出任何注解——并打印一条 warning，保证这个变化在传递性升级时可见；显式设置选项即可消除该警告。

两个开关及其取值含义

选项	unset（默认）	`false`	`true`
`generateJsonIncludeAnnotations`	不输出`@JsonInclude`，inclusion 完全由全局`ObjectMapper`决定，打印 warning	行为相同，但警告被消除	输出 spec-honest 的`@JsonInclude`注解（required 字段契约保护 + 下述 optional 非 nullable 策略）
`generateJsonSetterNullsAnnotations`	不输出`@JsonSetter(nulls = ...)`，打印 warning	行为相同，警告被消除	对 optional 非 nullable 属性输出`@JsonSetter(nulls = ...)`

各有一个配套的策略选项，只在对应主开关为true时生效：

optionalNonNullPropertyJsonInclude（默认NON_NULL）：optionalNonNullPropertyJsonInclude=true时，对 optional 非 nullable 属性输出的@JsonInclude策略，可选NON_NULL/NON_EMPTY/NON_DEFAULT/NONE（NONE表示不输出注解）。
optionalNonNullPropertyJsonSetterNulls（默认不设置）：显式指定SKIP/FAIL模式，把它与openApiNullable解耦。不设置时，模式与7.24.x完全一致地由openApiNullable推导（true→ 支持处为FAIL，false→SKIP）。显式设置后，之前不可达的组合也能做到——例如openApiNullable=true同时配SKIP：非 nullable 字段容忍 payload 中的显式null，而真正 nullable 的 optional 字段仍用JsonNullable<T>。

两个开关的完整说明见 spring 生成器文档和 kotlin-spring 生成器文档的选项表。

恢复 7.23.0 的输出（不输出注解）

如果你的项目之前依赖全局ObjectMapper控制序列化和 null 处理，升到7.25.0时直接保持现状即可：两个选项 unset 时默认就不输出注解，只是每次生成会看到 warning。想消除警告，就显式把它们都设为false。

CLI 方式：生成器专属选项通过--additional-properties以key=value逗号分隔传入（见 CLI 用法）：

openapi-generator-cli generate \ -i petstore.yaml \ -g spring \ -o out \ --additional-properties=generateJsonIncludeAnnotations=false,generateJsonSetterNullsAnnotations=false

选项也可以放进 JSON/YAML 配置文件，用-c config.json（或-c config.yaml）传入，不再写成长串--additional-properties。

Maven 插件方式：先把插件升到7.25.0，再按插件示例中的configOptions写法传选项：

<plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>7.25.0</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <inputSpec>${project.basedir}/swagger.yaml</inputSpec> <generatorName>spring</generatorName> <configOptions> <generateJsonIncludeAnnotations>false</generateJsonIncludeAnnotations> <generateJsonSetterNullsAnnotations>false</generateJsonSetterNullsAnnotations> </configOptions> </configuration> </execution> </executions> </plugin>

想保留注解时怎么开

如果你希望生成器输出 spec-honest 的注解，把对应开关显式设为true，并用配套选项微调 optional 非 nullable 属性的策略：

openapi-generator-cli generate \ -i petstore.yaml \ -g spring \ -o out \ --additional-properties=generateJsonIncludeAnnotations=true,optionalNonNullPropertyJsonInclude=NON_NULL,generateJsonSetterNullsAnnotations=true

kotlin-spring有一个需要特别注意的行为变化（见迁移指南）：在7.24.x中，optional 非 nullable 属性配openApiNullable=true生成时输出@JsonSetter(nulls = Nulls.FAIL)，payload 中的显式null会被直接拒绝；从7.25.0起，该注解只在generateJsonSetterNullsAnnotations=true时才输出，选项 unset（或false）时显式null交给全局ObjectMapper处理。如果你的 API 依赖这种严格拒绝（例如 PATCH 语义），设generateJsonSetterNullsAnnotations=true即可恢复Nulls.FAIL行为。

单属性级别的覆盖

两个生成器都支持 vendor extension 做逐属性覆盖，且优先级高于上述所有选项：

x-jackson-json-include-policy（FIELD 级）：手动指定该属性的@JsonInclude策略，取值ALWAYS、NON_NULL、NON_ABSENT、NON_EMPTY、NON_DEFAULT、USE_DEFAULTS、CUSTOM，或NONE表示不输出注解。无论generateJsonIncludeAnnotations是什么值都会生效。
x-jackson-json-setter-nulls（FIELD 级）：手动指定该属性的 null 处理，取值SKIP（忽略显式null，保留字段默认值）、FAIL（拒绝显式null）或NONE（不输出注解）。它优先于openApiNullable默认值和optionalNonNullPropertyJsonSetterNulls选项，并且即使generateJsonSetterNullsAnnotations未设置也会被尊重。

在 spec 中给特定属性加这些扩展，可以只在个别字段上做例外，而不是全局翻转注解策略。

结果验证

重新生成后，直接检查生成的模型源码：

两个开关为false（或 unset）时，模型属性上不应再出现字段级@JsonInclude和@JsonSetter(nulls = ...)，序列化和 null 处理回到全局ObjectMapper；
选项 unset 时生成日志会打印 warning，显式设置后 warning 消失——这是判断"选项已生效、行为已明确声明"的直接信号；
开关为true时，对应注解按配套策略出现在模型属性上。

两点语义边界要分清（迁移指南原文强调）：

@JsonSetter(nulls = Nulls.SKIP)与"不输出@JsonSetter"不等价：不输出注解时 Jackson 回落到全局默认Nulls.SET，显式null会覆盖字段默认值；而Nulls.SKIP会忽略传入的null、保留默认值。在spring生成器且openApiNullable=true时，选项 unset 仍然不输出注解（与7.24.x一致）但会打 warning；需要明确控制就设optionalNonNullPropertyJsonSetterNulls=SKIP（保留默认值）或FAIL（拒绝 null）。
@JsonInclude(NON_ABSENT)不再输出在JsonNullable<T>字段上：JsonNullable模块本身已经管理这些字段的 inclusion，注解是冗余的。