Add support for Optional<T> in Dart generator (both dart and dart-dio) to distinguish absent, null, and present states

Author: eirikb

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

@@ -1,9 +1,12 @@
 package org.openapitools.codegen.languages;
 
 import com.google.common.collect.Sets;
+import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.Operation;
 import io.swagger.v3.oas.models.media.Schema;
 import io.swagger.v3.oas.models.media.StringSchema;
+import io.swagger.v3.oas.models.parameters.Parameter;
+import io.swagger.v3.oas.models.parameters.RequestBody;
 import io.swagger.v3.oas.models.servers.Server;
 import lombok.Setter;
 import org.apache.commons.io.FilenameUtils;
@@ -45,6 +48,8 @@ public abstract class AbstractDartCodegen extends DefaultCodegen {
     public static final String PUB_REPOSITORY = "pubRepository";
     public static final String PUB_PUBLISH_TO = "pubPublishTo";
     public static final String USE_ENUM_EXTENSION = "useEnumExtension";
+    public static final String USE_OPTIONAL = "useOptional";
+    public static final String PATCH_ONLY = "patchOnly";
 
     @Setter protected String pubLibrary = "openapi.api";
     @Setter protected String pubName = "openapi";
@@ -56,8 +61,12 @@ public abstract class AbstractDartCodegen extends DefaultCodegen {
     @Setter protected String pubRepository = null;
     @Setter protected String pubPublishTo = null;
     @Setter protected boolean useEnumExtension = false;
+    @Setter protected boolean useOptional = false;
+    @Setter protected boolean patchOnly = false;
     @Setter protected String sourceFolder = "src";
     protected String libPath = "lib" + File.separator;
+
+    protected Set<String> patchRequestSchemas = new HashSet<>();
     protected String apiDocPath = "doc/";
     protected String modelDocPath = "doc/";
     protected String apiTestPath = "test" + File.separator;
@@ -195,6 +204,8 @@ public AbstractDartCodegen() {
         addOption(PUB_REPOSITORY, "Repository in generated pubspec", pubRepository);
         addOption(PUB_PUBLISH_TO, "Publish_to in generated pubspec", pubPublishTo);
         addOption(USE_ENUM_EXTENSION, "Allow the 'x-enum-values' extension for enums", String.valueOf(useEnumExtension));
+        addOption(USE_OPTIONAL, "Use Optional<T> to distinguish absent, null, and present for optional fields (Dart 3+)", String.valueOf(useOptional));
+        addOption(PATCH_ONLY, "Only apply Optional<T> to PATCH operation request bodies (requires useOptional=true)", String.valueOf(patchOnly));
         addOption(CodegenConstants.SOURCE_FOLDER, CodegenConstants.SOURCE_FOLDER_DESC, sourceFolder);
     }
 
@@ -301,6 +312,24 @@ public void processOpts() {
             additionalProperties.put(USE_ENUM_EXTENSION, useEnumExtension);
         }
 
+        if (additionalProperties.containsKey(USE_OPTIONAL)) {
+            this.setUseOptional(convertPropertyToBooleanAndWriteBack(USE_OPTIONAL));
+        } else {
+            additionalProperties.put(USE_OPTIONAL, useOptional);
+        }
+
+        if (additionalProperties.containsKey(PATCH_ONLY)) {
+            this.setPatchOnly(convertPropertyToBooleanAndWriteBack(PATCH_ONLY));
+        } else {
+            additionalProperties.put(PATCH_ONLY, patchOnly);
+        }
+
+        if (patchOnly && !useOptional) {
+            LOGGER.warn("patchOnly=true requires useOptional=true. Setting useOptional=true.");
+            this.setUseOptional(true);
+            additionalProperties.put(USE_OPTIONAL, true);
+        }
+
         if (additionalProperties.containsKey(CodegenConstants.SOURCE_FOLDER)) {
             String srcFolder = (String) additionalProperties.get(CodegenConstants.SOURCE_FOLDER);
             this.setSourceFolder(srcFolder.replace('/', File.separatorChar));
@@ -544,6 +573,35 @@ public String getTypeDeclaration(Schema p) {
         return super.getTypeDeclaration(p);
     }
 
+    @Override
+    public void preprocessOpenAPI(OpenAPI openAPI) {
+        super.preprocessOpenAPI(openAPI);
+
+        if (patchOnly && openAPI.getPaths() != null) {
+            openAPI.getPaths().forEach((path, pathItem) -> {
+                if (pathItem.getPatch() != null) {
+                    Operation patchOp = pathItem.getPatch();
+                    if (patchOp.getRequestBody() != null) {
+                        RequestBody requestBody = ModelUtils.getReferencedRequestBody(openAPI, patchOp.getRequestBody());
+                        if (requestBody != null && requestBody.getContent() != null) {
+                            requestBody.getContent().forEach((mediaType, content) -> {
+                                if (content.getSchema() != null) {
+                                    String ref = content.getSchema().get$ref();
+                                    if (ref != null) {
+                                        String schemaName = ModelUtils.getSimpleRef(ref);
+                                        String modelName = toModelName(schemaName);
+                                        patchRequestSchemas.add(modelName);
+                                        LOGGER.info("Identified '{}' as PATCH request schema (will use Optional<T>)", modelName);
+                                    }
+                                }
+                            });
+                        }
+                    }
+                }
+            });
+        }
+    }
+
     @Override
     public String getSchemaType(Schema p) {
         String openAPIType = super.getSchemaType(p);
@@ -558,7 +616,49 @@ public String getSchemaType(Schema p) {
 
     @Override
     public ModelsMap postProcessModels(ModelsMap objs) {
-        return postProcessModelsEnum(objs);
+        objs = postProcessModelsEnum(objs);
+
+        if (useOptional) {
+            for (ModelMap modelMap : objs.getModels()) {
+                CodegenModel model = modelMap.getModel();
+
+                boolean shouldUseOptional;
+
+                if (patchOnly) {
+                    shouldUseOptional = patchRequestSchemas.contains(model.classname);
+                } else {
+                    Boolean schemaUseOptional = (Boolean) model.vendorExtensions.get("x-use-optional");
+                    shouldUseOptional = schemaUseOptional != null && schemaUseOptional;
+                }
+
+                if (shouldUseOptional) {
+                    for (CodegenProperty prop : model.vars) {
+                        if (!prop.required && !prop.dataType.startsWith("Optional<")) {
+                            wrapPropertyWithOptional(prop);
+                        }
+                    }
+                }
+            }
+        }
+
+        return objs;
+    }
+
+    private void wrapPropertyWithOptional(CodegenProperty property) {
+        property.vendorExtensions.put("x-unwrapped-datatype", property.dataType);
+        property.vendorExtensions.put("x-is-optional", true);
+        property.vendorExtensions.put("x-original-is-number", property.isNumber);
+        property.vendorExtensions.put("x-original-is-integer", property.isInteger);
+
+        boolean hasNullableSuffix = property.dataType.endsWith("?");
+        String baseType = hasNullableSuffix ? property.dataType.substring(0, property.dataType.length() - 1) : property.dataType;
+        property.dataType = "Optional<" + baseType + "?" + ">";
+
+        if (property.datatypeWithEnum != null && !property.datatypeWithEnum.startsWith("Optional<")) {
+            hasNullableSuffix = property.datatypeWithEnum.endsWith("?");
+            baseType = hasNullableSuffix ? property.datatypeWithEnum.substring(0, property.datatypeWithEnum.length() - 1) : property.datatypeWithEnum;
+            property.datatypeWithEnum = "Optional<" + baseType + "?" + ">";
+        }
     }
 
     @Override
@@ -623,6 +723,19 @@ public CodegenProperty fromProperty(String name, Schema p, boolean required) {
         return property;
     }
 
+    @Override
+    public CodegenParameter fromParameter(Parameter parameter, Set<String> imports) {
+        final CodegenParameter param = super.fromParameter(parameter, imports);
+
+        if (useOptional && param.dataType != null && param.dataType.startsWith("Optional<")) {
+            param.dataType = param.dataType.substring("Optional<".length(), param.dataType.length() - 1);
+            param.vendorExtensions.remove("x-is-optional");
+            param.vendorExtensions.remove("x-unwrapped-datatype");
+        }
+
+        return param;
+    }
+
     @Override
     public CodegenOperation fromOperation(String path, String httpMethod, Operation operation, List<Server> servers) {
         final CodegenOperation op = super.fromOperation(path, httpMethod, operation, servers);
@@ -659,6 +772,21 @@ public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<Mo
         if (operations != null) {
             List<CodegenOperation> ops = operations.getOperation();
             for (CodegenOperation op : ops) {
+                if (patchOnly && "PATCH".equalsIgnoreCase(op.httpMethod)) {
+                    if (op.bodyParam != null && op.bodyParam.dataType != null) {
+                        String modelName = getString(op);
+                        patchRequestSchemas.add(modelName);
+                        LOGGER.debug("Marked schema '{}' for Optional wrapping (PATCH request body)", modelName);
+                    }
+                }
+
+                if (useOptional) {
+                    unwrapOptionalFromParameters(op.pathParams);
+                    unwrapOptionalFromParameters(op.queryParams);
+                    unwrapOptionalFromParameters(op.headerParams);
+                    unwrapOptionalFromParameters(op.formParams);
+                }
+
                 if (op.hasConsumes) {
                     if (!op.formParams.isEmpty() || op.isMultipart) {
                         // DefaultCodegen only sets this if the first consumes mediaType
@@ -680,6 +808,29 @@ public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<Mo
         return objs;
     }
 
+    private static String getString(CodegenOperation op) {
+        String modelName = op.bodyParam.dataType;
+        if (modelName.startsWith("List<") || modelName.startsWith("Map<")) {
+            int start = modelName.indexOf('<') + 1;
+            int end = modelName.lastIndexOf('>');
+            if (start > 0 && end > start) {
+                modelName = modelName.substring(start, end);
+            }
+        }
+        modelName = modelName.replace("?", "");
+        return modelName;
+    }
+
+    private void unwrapOptionalFromParameters(List<CodegenParameter> params) {
+        if (params == null) return;
+        for (CodegenParameter param : params) {
+            if (param.dataType != null && param.dataType.startsWith("Optional<")) {
+                param.dataType = param.dataType.substring("Optional<".length(), param.dataType.length() - 1);
+                param.vendorExtensions.remove("x-is-optional");
+            }
+        }
+    }
+
     private List<Map<String, String>> prioritizeContentTypes(List<Map<String, String>> consumes) {
         if (consumes.size() <= 1) {
             // no need to change any order

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

@@ -74,6 +74,11 @@ public void processOpts() {
         supportingFiles.add(new SupportingFile("auth/http_bearer_auth.mustache", authFolder, "http_bearer_auth.dart"));
         supportingFiles.add(new SupportingFile("auth/api_key_auth.mustache", authFolder, "api_key_auth.dart"));
         supportingFiles.add(new SupportingFile("auth/oauth.mustache", authFolder, "oauth.dart"));
+
+        if (useOptional) {
+            supportingFiles.add(new SupportingFile("optional.mustache", libPath, "optional.dart"));
+        }
+
         supportingFiles.add(new SupportingFile("git_push.sh.mustache", "", "git_push.sh"));
         supportingFiles.add(new SupportingFile("gitignore.mustache", "", ".gitignore"));
         supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));

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

@@ -220,6 +220,10 @@ public void processOpts() {
         supportingFiles.add(new SupportingFile("auth/oauth.mustache", authFolder, "oauth.dart"));
         supportingFiles.add(new SupportingFile("auth/auth.mustache", authFolder, "auth.dart"));
 
+        if (useOptional) {
+            supportingFiles.add(new SupportingFile("optional.mustache", srcFolder, "optional.dart"));
+        }
+
         configureSerializationLibrary(srcFolder);
         configureEqualityCheckMethod(srcFolder);
         configureDateLibrary(srcFolder);

modules/openapi-generator/src/main/resources/dart/libraries/dio/optional.mustache

@@ -0,0 +1,137 @@
+{{>header}}
+import 'package:json_annotation/json_annotation.dart';
+
+/// Represents an optional value that can be either absent or present.
+///
+/// This is used to distinguish between three states in PATCH operations:
+/// - Absent: Field is not set (omitted from JSON)
+/// - Present with null: Field is explicitly set to null
+/// - Present with value: Field has a value
+///
+/// Example usage:
+/// ```dart
+/// // Field absent - not sent in request
+/// final patch1 = Model();
+///
+/// // Field explicitly null - sends {"field": null}
+/// final patch2 = Model(field: const Optional.present(null));
+///
+/// // Field has value - sends {"field": "value"}
+/// final patch3 = Model(field: const Optional.present('value'));
+/// ```
+sealed class Optional<T> {
+  const Optional();
+
+  /// Creates an Optional with an absent value (not set).
+  const factory Optional.absent() = Absent<T>;
+
+  /// Creates an Optional with a present value (can be null).
+  const factory Optional.present(T value) = Present<T>;
+
+  /// Returns true if this Optional has a value (even if that value is null).
+  bool get isPresent;
+
+  /// Returns true if this Optional does not have a value.
+  bool get isEmpty => !isPresent;
+
+  /// Returns the value if present, throws if absent.
+  T get value;
+
+  /// Returns the value if present, otherwise returns [defaultValue].
+  T orElse(T defaultValue);
+
+  /// Returns the value if present, otherwise returns the result of calling [defaultValue].
+  T orElseGet(T Function() defaultValue);
+
+  /// Maps the value if present using [transform], otherwise returns an absent Optional.
+  Optional<R> map<R>(R Function(T value) transform);
+}
+
+/// Represents an absent Optional value.
+final class Absent<T> extends Optional<T> {
+  const Absent();
+
+  @override
+  bool get isPresent => false;
+
+  @override
+  T get value => throw StateError('No value present');
+
+  @override
+  T orElse(T defaultValue) => defaultValue;
+
+  @override
+  T orElseGet(T Function() defaultValue) => defaultValue();
+
+  @override
+  Optional<R> map<R>(R Function(T value) transform) => const Absent();
+
+  @override
+  bool operator ==(Object other) => other is Absent<T>;
+
+  @override
+  int get hashCode => 0;
+
+  @override
+  String toString() => 'Optional.absent()';
+}
+
+/// Represents a present Optional value.
+final class Present<T> extends Optional<T> {
+  const Present(this._value);
+
+  final T _value;
+
+  @override
+  bool get isPresent => true;
+
+  @override
+  T get value => _value;
+
+  @override
+  T orElse(T defaultValue) => _value;
+
+  @override
+  T orElseGet(T Function() defaultValue) => _value;
+
+  @override
+  Optional<R> map<R>(R Function(T value) transform) => Optional.present(transform(_value));
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      (other is Present<T> && _value == other._value);
+
+  @override
+  int get hashCode => _value.hashCode;
+
+  @override
+  String toString() => 'Optional.present($_value)';
+}
+
+/// JSON converter for Optional<T> values.
+///
+/// This converter handles serialization and deserialization of Optional values:
+/// - Optional.absent() -> field omitted from JSON
+/// - Optional.present(null) -> {"field": null}
+/// - Optional.present(value) -> {"field": value}
+///
+/// Usage with json_serializable:
+/// ```dart
+/// @JsonKey()
+/// @OptionalConverter()
+/// final Optional<String?> field;
+/// ```
+class OptionalConverter<T> implements JsonConverter<Optional<T>, T?> {
+  const OptionalConverter();
+
+  @override
+  Optional<T> fromJson(T? json) {
+    return json == null ? const Optional.absent() : Optional.present(json);
+  }
+
+  @override
+  T? toJson(Optional<T> object) {
+    return object.isPresent ? object.value : null;
+  }
+}