feat: add optional getters for nullable fields

.tool-versions

@@ -0,0 +1 @@
+ivm-java openjdk-21.0.8

bin/configs/java-restclient-springBoot4-jackson3-jspecify-optional-getters.yaml

@@ -0,0 +1,18 @@
+generatorName: java
+outputDir: samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters
+library: restclient
+inputSpec: modules/openapi-generator/src/test/resources/3_0/java/jspecify.yaml
+templateDir: modules/openapi-generator/src/main/resources/Java
+validateSpec: false
+additionalProperties:
+  artifactId: petstore-restclient-optional-getters
+  hideGenerationTimestamp: "true"
+  containerDefaultToNull: "true"
+  useSpringBoot4: true
+  useJackson3: true
+  openApiNullable: false
+  useJspecify: true
+  optionalGettersForNullableFieldsOnly: "true"
+typeMappings:
+  OffsetDateTime: java.time.Instant
+  BigDecimal: java.math.BigDecimal

bin/configs/java-resttemplate-springBoot4-jackson3-jspecify-optional-getters.yaml

@@ -0,0 +1,19 @@
+generatorName: java
+outputDir: samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters
+library: resttemplate
+inputSpec: modules/openapi-generator/src/test/resources/3_0/java/jspecify.yaml
+templateDir: modules/openapi-generator/src/main/resources/Java
+validateSpec: false
+additionalProperties:
+  artifactId: petstore-resttemplate-optional-getters
+  hideGenerationTimestamp: "true"
+  containerDefaultToNull: "true"
+  useJakartaEe: true
+  useSpringBoot4: true
+  useJackson3: true
+  openApiNullable: false
+  useJspecify: true
+  optionalGettersForNullableFieldsOnly: "true"
+typeMappings:
+  OffsetDateTime: java.time.Instant
+  BigDecimal: java.math.BigDecimal

bin/configs/java-webclient-springBoot4-jackson3-jspecify-optional-getters.yaml

@@ -0,0 +1,18 @@
+generatorName: java
+outputDir: samples/client/petstore/java/webclient-springBoot4-jackson3-jspecify-optional-getters
+library: webclient
+inputSpec: modules/openapi-generator/src/test/resources/3_0/java/jspecify.yaml
+templateDir: modules/openapi-generator/src/main/resources/Java
+validateSpec: false
+additionalProperties:
+  artifactId: petstore-webclient-optional-getters
+  hideGenerationTimestamp: "true"
+  containerDefaultToNull: "true"
+  useSpringBoot4: true
+  useJackson3: true
+  openApiNullable: false
+  useJspecify: true
+  optionalGettersForNullableFieldsOnly: "true"
+typeMappings:
+  OffsetDateTime: java.time.Instant
+  BigDecimal: java.math.BigDecimal

bin/configs/spring-boot-4-jspecify-optional-getters.yaml

@@ -0,0 +1,22 @@
+generatorName: spring
+library: spring-boot
+outputDir: samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters
+inputSpec: modules/openapi-generator/src/test/resources/3_0/java/jspecify.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaSpring
+validateSpec: false
+additionalProperties:
+  groupId: org.openapitools.openapi3
+  documentationProvider: springdoc
+  interfaceOnly: true
+  artifactId: springboot-optional-getters
+  snapshotVersion: "true"
+  useSpringBoot4: true
+  useJackson3: true
+  useBeanValidation: true
+  withXml: true
+  hideGenerationTimestamp: "true"
+  generateConstructorWithAllArgs: true
+  generateBuilders: true
+  openApiNullable: false
+  useJspecify: true
+  optionalGettersForNullableFieldsOnly: "true"

docs/generators/elixir.md

@@ -24,7 +24,6 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |enumUnknownDefaultCase|If the server adds new enum cases, that are unknown by an old spec/client, the client will fail to parse the network response. With this option enabled, each enum will have a new case, 'unknown_default_open_api', so that when the server sends an enum case that is not known by the client/spec, they can safely fallback to this case.|<dl><dt>**false**</dt><dd>No changes to the enums are made, this is the default option.</dd><dt>**true**</dt><dd>With this option enabled, each enum will have a new case, 'unknown_default_open_api', so that when the enum case sent by the server is not known by the client/spec, can safely be decoded to this case.</dd></dl>|false|
 |invokerPackage|The main namespace to use for all classes. e.g. Yay.Pets| |null|
 |legacyDiscriminatorBehavior|Set to false for generators with better support for discriminators. (Python, Java, Go, PowerShell, C# have this enabled by default).|<dl><dt>**true**</dt><dd>The mapping in the discriminator includes descendent schemas that allOf inherit from self and the discriminator mapping schemas in the OAS document.</dd><dt>**false**</dt><dd>The mapping in the discriminator includes any descendent schemas that allOf inherit from self, any oneOf schemas, any anyOf schemas, any x-discriminator-values, and the discriminator mapping schemas in the OAS document AND Codegen validates that oneOf and anyOf schemas contain the required discriminator and throws an error if the discriminator is missing.</dd></dl>|true|
-|library|HTTP library template (sub-template) to use|<dl><dt>**tesla**</dt><dd>Tesla &gt;= 1.14 (https://github.com/elixir-tesla/tesla)</dd><dt>**req**</dt><dd>Req &gt;= 0.6.0 (excluding 0.7.0-0.7.2) (https://github.com/wojtekmach/req)</dd></dl>|tesla|
 |licenseHeader|The license header to prepend to the top of all source files.| |null|
 |packageName|Elixir package name (convention: lowercase).| |null|
 |prependFormOrBodyParameters|Add form or body parameters to the beginning of the parameter list.| |false|

docs/generators/java-microprofile.md

@@ -56,7 +56,6 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |generateBuilders|Whether to generate builders for models| |false|
 |generateClientAsBean|For resttemplate, restclient and webclient, configure whether to create `ApiClient.java` and Apis clients as bean (with `@Component` annotation).| |false|
 |generateConstructorWithAllArgs|whether to generate a constructor for all arguments| |false|
-|generateInsecureTlsHook|Generate the ApiClient.disableCertificateValidation hook, which trusts all TLS certificates (default to true). Set to false to omit it, e.g. when static analysis flags the trust-all TrustManager it contains. Available on `jersey2`, `jersey3` libraries.| |true|
 |gradleProperties|Append additional Gradle properties to the gradle.properties file| |null|
 |groupId|groupId in generated pom.xml| |org.openapitools|
 |hideGenerationTimestamp|Hides the generation timestamp when files are generated.| |false|

docs/generators/java.md

@@ -56,7 +56,6 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |generateBuilders|Whether to generate builders for models| |false|
 |generateClientAsBean|For resttemplate, restclient and webclient, configure whether to create `ApiClient.java` and Apis clients as bean (with `@Component` annotation).| |false|
 |generateConstructorWithAllArgs|whether to generate a constructor for all arguments| |false|
-|generateInsecureTlsHook|Generate the ApiClient.disableCertificateValidation hook, which trusts all TLS certificates (default to true). Set to false to omit it, e.g. when static analysis flags the trust-all TrustManager it contains. Available on `jersey2`, `jersey3` libraries.| |true|
 |gradleProperties|Append additional Gradle properties to the gradle.properties file| |null|
 |groupId|groupId in generated pom.xml| |org.openapitools|
 |hideGenerationTimestamp|Hides the generation timestamp when files are generated.| |false|

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

@@ -118,6 +118,7 @@ public abstract class AbstractJavaCodegen extends DefaultCodegen implements Code
     public static final String DEFAULT_TEST_FOLDER = "${project.build.directory}/generated-test-sources/openapi";
     public static final String GENERATE_CONSTRUCTOR_WITH_ALL_ARGS = "generateConstructorWithAllArgs";
     public static final String GENERATE_BUILDERS = "generateBuilders";
+    public static final String OPTIONAL_GETTERS_FOR_NULLABLE_FIELDS_ONLY = "optionalGettersForNullableFieldsOnly";
 
     @Getter @Setter
     protected String dateLibrary = "java8";
@@ -181,6 +182,8 @@ protected enum ENUM_PROPERTY_NAMING_TYPE {MACRO_CASE, legacy, original}
     @Getter @Setter
     protected String booleanGetterPrefix = "get";
     @Setter protected boolean ignoreAnyOfInEnum = false;
+    @Getter @Setter
+    protected boolean optionalGettersForNullableFieldsOnly = false;
     @Setter protected String parentGroupId = "";
     @Setter protected String parentArtifactId = "";
     @Setter protected String parentVersion = "";
@@ -371,6 +374,7 @@ public AbstractJavaCodegen() {
         cliOptions.add(CliOption.newBoolean(CONTAINER_DEFAULT_TO_NULL, "Set containers (array, set, map) default to null"));
         cliOptions.add(CliOption.newBoolean(GENERATE_CONSTRUCTOR_WITH_ALL_ARGS, "whether to generate a constructor for all arguments").defaultValue(Boolean.FALSE.toString()));
         cliOptions.add(CliOption.newBoolean(GENERATE_BUILDERS, "Whether to generate builders for models").defaultValue(Boolean.FALSE.toString()));
+        cliOptions.add(CliOption.newBoolean(OPTIONAL_GETTERS_FOR_NULLABLE_FIELDS_ONLY, "Make getters of non-required fields return Optional<T> while keeping the field and setter as the raw type. Supported libraries: restclient, resttemplate, webclient (java generator) and spring (spring generator). Opt-in, disabled by default.", optionalGettersForNullableFieldsOnly));
         cliOptions.add(CliOption.newBoolean(DISABLE_DISCRIMINATOR_JSON_IGNORE_PROPERTIES, "Ignore discriminator field type for Jackson serialization", disableDiscriminatorJsonIgnoreProperties));
 
         cliOptions.add(CliOption.newString(CodegenConstants.PARENT_GROUP_ID, CodegenConstants.PARENT_GROUP_ID_DESC));
@@ -453,6 +457,7 @@ public void processOpts() {
 
         convertPropertyToBooleanAndWriteBack(GENERATE_CONSTRUCTOR_WITH_ALL_ARGS, this::setGenerateConstructorWithAllArgs);
         convertPropertyToBooleanAndWriteBack(GENERATE_BUILDERS, this::setGenerateBuilders);
+        convertPropertyToBooleanAndWriteBack(OPTIONAL_GETTERS_FOR_NULLABLE_FIELDS_ONLY, this::setOptionalGettersForNullableFieldsOnly);
         convertPropertyToBooleanAndWriteBack(DISABLE_DISCRIMINATOR_JSON_IGNORE_PROPERTIES, this::setDisableDiscriminatorJsonIgnoreProperties);
         if (StringUtils.isEmpty(System.getenv("JAVA_POST_PROCESS_FILE"))) {
             LOGGER.info("Environment variable JAVA_POST_PROCESS_FILE not defined so the Java code may not be properly formatted. To define it, try 'export JAVA_POST_PROCESS_FILE=\"/usr/local/bin/clang-format -i\"' (Linux/Mac)");
@@ -801,6 +806,39 @@ public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs)
             }
         }
 
+        // When optionalGettersForNullableFieldsOnly is enabled, propagate isDiscriminator=true
+        // to subtype models that redefine a discriminator property from a parent/interface.
+        // Without this, the template would generate Optional<T> for those fields, causing a
+        // return-type incompatibility with the abstract getter declared by the parent interface.
+        if (optionalGettersForNullableFieldsOnly) {
+            for (ModelsMap modelsAttrs : objs.values()) {
+                for (ModelMap mo : modelsAttrs.getModels()) {
+                    CodegenModel cm = mo.getModel();
+                    if (cm.discriminator != null) {
+                        String discPropName = cm.discriminator.getPropertyBaseName();
+                        // propagate to all known subtype models
+                        if (cm.discriminator.getMappedModels() != null) {
+                            for (CodegenDiscriminator.MappedModel mapped : cm.discriminator.getMappedModels()) {
+                                CodegenModel subModel = allModels.get(mapped.getModelName());
+                                if (subModel != null) {
+                                    for (CodegenProperty var : subModel.vars) {
+                                        if (discPropName.equals(var.baseName)) {
+                                            var.isDiscriminator = true;
+                                        }
+                                    }
+                                    for (CodegenProperty var : subModel.allVars) {
+                                        if (discPropName.equals(var.baseName)) {
+                                            var.isDiscriminator = true;
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
         if (isGenerateConstructorWithAllArgs()) {
             // conditionally force the generation of all args constructor.
             for (CodegenModel cm : allModels.values()) {

modules/openapi-generator/src/main/resources/Java/libraries/restclient/pojo.mustache

@@ -218,7 +218,7 @@ public {{>sealed}}class {{classname}} {{#parent}}extends {{{.}}} {{/parent}}{{#v
 {{#deprecated}}
   @Deprecated
 {{/deprecated}}
-  {{>nullable_var_annotations}}{{! prevent indent}}
+  {{^optionalGettersForNullableFieldsOnly}}{{>nullable_var_annotations}}{{/optionalGettersForNullableFieldsOnly}}{{#optionalGettersForNullableFieldsOnly}}{{#required}}{{>nullable_var_annotations}}{{/required}}{{^required}}{{#isInherited}}{{>nullable_var_annotations}}{{/isInherited}}{{#isDiscriminator}}{{>nullable_var_annotations}}{{/isDiscriminator}}{{/required}}{{/optionalGettersForNullableFieldsOnly}}{{! prevent indent}}
 {{#jsonb}}
   @JsonbProperty("{{baseName}}")
 {{/jsonb}}
@@ -240,18 +240,12 @@ public {{>sealed}}class {{classname}} {{#parent}}extends {{{.}}} {{/parent}}{{#v
   @JsonIgnore
 {{/vendorExtensions.x-is-jackson-optional-nullable}}
 {{^vendorExtensions.x-is-jackson-optional-nullable}}{{#jackson}}{{> jackson_annotations}}{{/jackson}}{{/vendorExtensions.x-is-jackson-optional-nullable}}
-  public {{>nullableDatatypeWithEnum}} {{getter}}() {
-    {{#vendorExtensions.x-is-jackson-optional-nullable}}
-    {{#isReadOnly}}{{! A readonly attribute doesn't have setter => jackson will set null directly if explicitly returned by API, so make sure we have an empty JsonNullable}}
+  public {{#optionalGettersForNullableFieldsOnly}}{{^required}}{{^isInherited}}{{^isDiscriminator}}{{^vendorExtensions.x-is-jackson-optional-nullable}}java.util.Optional<{{/vendorExtensions.x-is-jackson-optional-nullable}}{{/isDiscriminator}}{{/isInherited}}{{/required}}{{/optionalGettersForNullableFieldsOnly}}{{>nullableDatatypeWithEnum}}{{#optionalGettersForNullableFieldsOnly}}{{^required}}{{^isInherited}}{{^isDiscriminator}}{{^vendorExtensions.x-is-jackson-optional-nullable}}>{{/vendorExtensions.x-is-jackson-optional-nullable}}{{/isDiscriminator}}{{/isInherited}}{{/required}}{{/optionalGettersForNullableFieldsOnly}} {{getter}}() {
+    {{#vendorExtensions.x-is-jackson-optional-nullable}}{{#isReadOnly}}{{! A readonly attribute doesn't have setter => jackson will set null directly if explicitly returned by API, so make sure we have an empty JsonNullable}}
     if ({{name}} == null) {
       {{name}} = JsonNullable.<{{{datatypeWithEnum}}}>{{#defaultValue}}of({{{.}}}){{/defaultValue}}{{^defaultValue}}undefined(){{/defaultValue}};
     }
-    {{/isReadOnly}}
-    return {{name}}.orElse(null);
-    {{/vendorExtensions.x-is-jackson-optional-nullable}}
-    {{^vendorExtensions.x-is-jackson-optional-nullable}}
-    return {{name}};
-    {{/vendorExtensions.x-is-jackson-optional-nullable}}
+    {{/isReadOnly}}return {{name}}.orElse(null);{{/vendorExtensions.x-is-jackson-optional-nullable}}{{^vendorExtensions.x-is-jackson-optional-nullable}}return {{#optionalGettersForNullableFieldsOnly}}{{^required}}{{^isInherited}}{{^isDiscriminator}}java.util.Optional.ofNullable({{name}}){{/isDiscriminator}}{{#isDiscriminator}}{{name}}{{/isDiscriminator}}{{/isInherited}}{{#isInherited}}{{name}}{{/isInherited}}{{/required}}{{#required}}{{name}}{{/required}}{{/optionalGettersForNullableFieldsOnly}}{{^optionalGettersForNullableFieldsOnly}}{{name}}{{/optionalGettersForNullableFieldsOnly}};{{/vendorExtensions.x-is-jackson-optional-nullable}}
   }
 
   {{#vendorExtensions.x-is-jackson-optional-nullable}}

modules/openapi-generator/src/main/resources/Java/libraries/resttemplate/pojo.mustache

@@ -218,7 +218,7 @@ public class {{classname}} {{#parent}}extends {{{.}}} {{/parent}}{{#vendorExtens
 {{#deprecated}}
   @Deprecated
 {{/deprecated}}
-  {{>nullable_var_annotations}}{{! prevent indent}}
+  {{^optionalGettersForNullableFieldsOnly}}{{>nullable_var_annotations}}{{/optionalGettersForNullableFieldsOnly}}{{#optionalGettersForNullableFieldsOnly}}{{#required}}{{>nullable_var_annotations}}{{/required}}{{^required}}{{#isInherited}}{{>nullable_var_annotations}}{{/isInherited}}{{#isDiscriminator}}{{>nullable_var_annotations}}{{/isDiscriminator}}{{/required}}{{/optionalGettersForNullableFieldsOnly}}{{! prevent indent}}
 {{#jsonb}}
   @JsonbProperty("{{baseName}}")
 {{/jsonb}}
@@ -240,18 +240,12 @@ public class {{classname}} {{#parent}}extends {{{.}}} {{/parent}}{{#vendorExtens
   @JsonIgnore
 {{/vendorExtensions.x-is-jackson-optional-nullable}}
 {{^vendorExtensions.x-is-jackson-optional-nullable}}{{#jackson}}{{> jackson_annotations}}{{/jackson}}{{/vendorExtensions.x-is-jackson-optional-nullable}}
-  public {{>nullableDatatypeWithEnum}} {{getter}}() {
-    {{#vendorExtensions.x-is-jackson-optional-nullable}}
-    {{#isReadOnly}}{{! A readonly attribute doesn't have setter => jackson will set null directly if explicitly returned by API, so make sure we have an empty JsonNullable}}
+  public {{#optionalGettersForNullableFieldsOnly}}{{^required}}{{^isInherited}}{{^isDiscriminator}}{{^vendorExtensions.x-is-jackson-optional-nullable}}java.util.Optional<{{/vendorExtensions.x-is-jackson-optional-nullable}}{{/isDiscriminator}}{{/isInherited}}{{/required}}{{/optionalGettersForNullableFieldsOnly}}{{>nullableDatatypeWithEnum}}{{#optionalGettersForNullableFieldsOnly}}{{^required}}{{^isInherited}}{{^isDiscriminator}}{{^vendorExtensions.x-is-jackson-optional-nullable}}>{{/vendorExtensions.x-is-jackson-optional-nullable}}{{/isDiscriminator}}{{/isInherited}}{{/required}}{{/optionalGettersForNullableFieldsOnly}} {{getter}}() {
+    {{#vendorExtensions.x-is-jackson-optional-nullable}}{{#isReadOnly}}{{! A readonly attribute doesn't have setter => jackson will set null directly if explicitly returned by API, so make sure we have an empty JsonNullable}}
     if ({{name}} == null) {
       {{name}} = JsonNullable.<{{{datatypeWithEnum}}}>{{#defaultValue}}of({{{.}}}){{/defaultValue}}{{^defaultValue}}undefined(){{/defaultValue}};
     }
-    {{/isReadOnly}}
-    return {{name}}.orElse(null);
-    {{/vendorExtensions.x-is-jackson-optional-nullable}}
-    {{^vendorExtensions.x-is-jackson-optional-nullable}}
-    return {{name}};
-    {{/vendorExtensions.x-is-jackson-optional-nullable}}
+    {{/isReadOnly}}return {{name}}.orElse(null);{{/vendorExtensions.x-is-jackson-optional-nullable}}{{^vendorExtensions.x-is-jackson-optional-nullable}}return {{#optionalGettersForNullableFieldsOnly}}{{^required}}{{^isInherited}}{{^isDiscriminator}}java.util.Optional.ofNullable({{name}}){{/isDiscriminator}}{{#isDiscriminator}}{{name}}{{/isDiscriminator}}{{/isInherited}}{{#isInherited}}{{name}}{{/isInherited}}{{/required}}{{#required}}{{name}}{{/required}}{{/optionalGettersForNullableFieldsOnly}}{{^optionalGettersForNullableFieldsOnly}}{{name}}{{/optionalGettersForNullableFieldsOnly}};{{/vendorExtensions.x-is-jackson-optional-nullable}}
   }
 
   {{#vendorExtensions.x-is-jackson-optional-nullable}}