本文探讨在使用 openapi-generator-maven-plugin 生成 java 模型类时，是否应禁用默认 getter/setter 等访问方法、转而依赖 lombok 注解——结论是：不推荐修改模板剔除方法，而应通过 vendor extensions（如 x-class-extra-annotation）安全扩展，兼顾标准兼容性与开发效率。
OpenAPI Generator 的核心价值在于生成开箱即用、语义完备、生态兼容的模型类。它默认为每个 POJO 生成符合 Java Bean 规范的字段、getter/setter、构造器、equals()/hashCode()/toString()，并原生集成 Jackson 序列化、Bean Validation（如 @NotNull、@Size）及 OpenAPI 厂商扩展支持。这些能力并非“冗余代码”，而是保障 API 客户端/服务端行为一致性的基础设施。
直接通过定制 Mustache 模板（如修改 pojo.mustache）移除所有访问方法，虽技术上可行，但会带来显著维护成本与功能折损：
- ❌ 失去 Bean Validation 元数据的运行时绑定（如 Spring Boot 自动校验失效）；
- ❌ Jackson 可能无法正确序列化/反序列化（尤其涉及 @JsonCreator、@JsonProperty 等隐式推导逻辑）；
- ❌ 无法利用 x-field-extra-annotation、x-class-extra-annotation 等标准化 vendor extensions 动态注入注解；
- ❌ Lombok 配置（如 @Builder(builderClassName = "XXX")、@SuperBuilder 选择、@JsonIgnore 条件控制）需大量模板参数与上下文判断，极易出错且难以复用。
✅ 推荐方案：保持默认生成逻辑 + 声明式增强
-
在 OpenAPI YAML/JSON 中为模型添加 vendor extensions
components: schemas: User: x-class-extra-annotation: "@lombok.Data @lombok.Builder" properties: id: type: integer x-field-extra-annotation: "@com.fasterxml.jackson.annotation.JsonIgnore" name: type: string x-field-extra-annotation: "@javax.validation.constraints.NotBlank" -
Maven 插件配置启用 vendor extension 支持（无需额外模板）
org.openapitools openapi-generator-maven-plugin 7.8.0 java src/gen/java true @lombok.Data -
关键注意事项
- additionalModelTypeAnnotations 是全局生效的简洁方式，适用于所有模型类统一加 @Data；
- x-class-extra-annotation 和 x-field-extra-annotation 提供细粒度控制，优先级更高，适合差异化场景；
- 若需 @Builder 的高级特性（如 toBuilder=true），建议在生成后通过 IDE 或脚本二次处理，或评估是否真有必要——多数 DTO 场景 @Data 已足够；
- 永远不要删除默认访问方法：它们是 OpenAPI Generator 与其他生态组件（如 Springdoc、Micrometer、Hibernate Validator）协同工作的契约基础。
总结而言，OpenAPI Generator 不是“代码生成器”，而是“契约驱动的模型协调器”。与其对抗其设计哲学、陷入模板泥潭，不如善用其开放的扩展机制，在标准之上做轻量增强。这既保障了长期可维护性，也真正释放了契约即文档、契约即代码的生产力价值。
