Support sealed classes on json_serializeble, dart_mappable (#383)

Co-authored-by: Claude <[email protected]>

Author: dfdgsdfg

swagger_parser/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 1.31.0
+- Add complete sealed classes(`oneOf`/`anyOf`) support for `json_serializeble` serializer
+  - **WARNING**: Undiscriminated sealed classes use O(n) try-catch deserialization where n is the number of variants
+  - **RECOMMENDED**: Add discriminator properties to your OpenAPI specification for O(1) performance
+  - Add support for sealed classes fallback for failed decoding
+- Add complete sealed classes(`oneOf`/`anyOf`) support for `dart_mappable` serializer
+  - **WARNING**: Undiscriminated sealed classes use O(n) try-catch deserialization where n is the number of variants
+  - **RECOMMENDED**: Add discriminator properties to your OpenAPI specification for O(1) performance
+  - Add support for sealed classes fallback for failed decoding
+- Add `dart_mappable_convenient_when` option to control union type generation for `dart_mappable` serializer
+  - `dart_mappable_convenient_when: true` - generates legacy `when<T>, maybeWhen<T>` methods
+  - `dart_mappable_convenient_when: false` (default) - generates sealed classes for better type safety
+- Add `@Deprecated()` annotation to `when<T>, maybeWhen<T>` method with dart_mappable. Use dart pattern matching
+- Fix creating duplicated `unknown` property enum with dart_mappable and `unknown_enum_value: true`
+
 ## 1.30.1
 - Fix resolve inline schemas nested within tagged operations
 

swagger_parser/README.md

@@ -148,13 +148,19 @@ swagger_parser:
   # Set 'false' to maintain compatibility with Freezed 2.x.
   use_freezed3: false
 
-  # Optional (dart & freezed only). Set string value to use fallbackUnion parameter when using Freezed annotation.
-  # When set to a string value, adds fallbackUnion: <value> to the @Freezed annotation.
-  # When not set (null) or empty, the @Freezed annotation has no fallbackUnion parameter.
+  # Optional (dart & freezed/dart_mappable). Set string value to use fallbackUnion parameter.
+  # For freezed: adds fallbackUnion: <value> to the @Freezed annotation.
+  # For dart_mappable: creates additional fallback variant for unknown discriminator values.
+  # When not set (null) or empty, no fallback union is generated.
   # Examples: "unknown"
   # Default: "" (no fallbackUnion parameter)
   fallback_union: ""
 
+  # Optional (dart_mappable only). Set false to generate sealed classes for union types.
+  # Set true to generate when/maybeWhen convenience methods for legacy support of deprecated union features from versions prior to 3.31.
+  # Default: false
+  dart_mappable_convenient_when: false
+
   # DART ONLY
   # Optional. Set `true` to use MultipartFile instead of File as argument type for file parameters.
   use_multipart_file: false

swagger_parser/lib/src/config/swp_config.dart

@@ -39,6 +39,7 @@ class SWPConfig {
     this.useFreezed3 = false,
     this.useMultipartFile = false,
     this.fallbackUnion,
+    this.dartMappableConvenientWhen = false,
     this.excludeTags = const <String>[],
     this.includeTags = const <String>[],
     this.fallbackClient = 'fallback',
@@ -78,6 +79,7 @@ class SWPConfig {
     required this.includeTags,
     required this.fallbackClient,
     required this.mergeOutputs,
+    required this.dartMappableConvenientWhen,
     this.fallbackUnion,
   });
 
@@ -233,6 +235,11 @@ class SWPConfig {
     final fallbackUnion =
         yamlMap['fallback_union'] as String? ?? rootConfig?.fallbackUnion;
 
+    final dartMappableConvenientWhen =
+        yamlMap['dart_mappable_convenient_when'] as bool? ??
+            rootConfig?.dartMappableConvenientWhen ??
+            true;
+
     final excludedTagsYaml = yamlMap['exclude_tags'] as YamlList?;
     List<String>? excludedTags;
     if (excludedTagsYaml != null) {
@@ -309,6 +316,7 @@ class SWPConfig {
       includeTags: includedTags ?? dc.includeTags,
       fallbackClient: fallbackClient ?? dc.fallbackClient,
       mergeOutputs: mergeOutputs ?? dc.mergeOutputs,
+      dartMappableConvenientWhen: dartMappableConvenientWhen,
     );
   }
 
@@ -458,6 +466,11 @@ class SWPConfig {
   /// Optional. Set fallback consctructor name to use fallbackUnion parameter when using Freezed annotation.
   final String? fallbackUnion;
 
+  /// DART ONLY
+  /// Optional. Set 'true' to generate when/maybeWhen convenience methods for dart_mappable unions.
+  /// Set 'false' to use only native Dart pattern matching.
+  final bool dartMappableConvenientWhen;
+
   /// DART ONLY
   /// Optional. Set excluded tags.
   ///
@@ -507,6 +520,7 @@ class SWPConfig {
       useFreezed3: useFreezed3,
       useMultipartFile: useMultipartFile,
       fallbackUnion: fallbackUnion,
+      dartMappableConvenientWhen: dartMappableConvenientWhen,
       mergeOutputs: mergeOutputs,
     );
   }

swagger_parser/lib/src/generator/config/generator_config.dart

@@ -27,6 +27,7 @@ class GeneratorConfig {
     this.useFreezed3 = false,
     this.useMultipartFile = false,
     this.fallbackUnion,
+    this.dartMappableConvenientWhen = true,
     this.mergeOutputs = false,
   });
 
@@ -126,6 +127,11 @@ class GeneratorConfig {
   /// Optional. Set fallback constructor name to use fallbackUnion parameter when using Freezed annotation.
   final String? fallbackUnion;
 
+  /// DART ONLY
+  /// Optional. Set 'true' to generate when/maybeWhen convenience methods for dart_mappable unions.
+  /// Set 'false' to use only native Dart pattern matching.
+  final bool dartMappableConvenientWhen;
+
   /// Optional. Set to true to merge all generated code into a single file.
   ///
   /// This is useful when using swagger_parser together with build_runner, which needs to map

swagger_parser/lib/src/generator/generator/fill_controller.dart

@@ -3,6 +3,7 @@ import '../../parser/swagger_parser_core.dart';
 import '../../utils/base_utils.dart';
 import '../config/generator_config.dart';
 import '../model/generated_file.dart';
+import '../model/json_serializer.dart';
 import '../model/programming_language.dart';
 
 /// Handles generating files
@@ -21,9 +22,8 @@ final class FillController {
 
   /// Return [GeneratedFile] generated from given [UniversalDataClass]
   GeneratedFile fillDtoContent(UniversalDataClass dataClass) => GeneratedFile(
-        name: 'models/'
-            '${config.language == ProgrammingLanguage.dart ? dataClass.name.toSnake : dataClass.name.toPascal}'
-            '.${config.language.fileExtension}',
+        name:
+            'models/${_resolveDtoFileBaseName(dataClass)}.${config.language.fileExtension}',
         content: config.language.dtoFileContent(
           dataClass,
           jsonSerializer: config.jsonSerializer,
@@ -33,10 +33,45 @@ final class FillController {
           generateValidator: config.generateValidator,
           useFreezed3: config.useFreezed3,
           useMultipartFile: config.useMultipartFile,
+          dartMappableConvenientWhen: config.dartMappableConvenientWhen,
           fallbackUnion: config.fallbackUnion,
         ),
       );
 
+  String _resolveDtoFileBaseName(UniversalDataClass dataClass) {
+    if (config.language != ProgrammingLanguage.dart) {
+      return dataClass.name.toPascal;
+    }
+
+    var baseName = dataClass.name;
+
+    if (config.jsonSerializer != JsonSerializer.freezed &&
+        dataClass is UniversalComponentClass) {
+      final isUnion = dataClass.discriminator != null ||
+          (dataClass.undiscriminatedUnionVariants?.isNotEmpty ?? false);
+      if (isUnion) {
+        baseName = _applySealedNaming(baseName);
+      }
+    }
+
+    return baseName.toSnake;
+  }
+
+  String _applySealedNaming(String name) {
+    const unionSuffix = 'Union';
+    const sealedSuffix = 'Sealed';
+
+    if (name.endsWith(sealedSuffix)) {
+      return name;
+    }
+
+    if (name.endsWith(unionSuffix)) {
+      return '${name.substring(0, name.length - unionSuffix.length)}$sealedSuffix';
+    }
+
+    return name;
+  }
+
   /// Return [GeneratedFile] generated from given [UniversalRestClient]
   GeneratedFile fillRestClientContent(UniversalRestClient restClient) {
     final postfix = config.clientPostfix ?? 'Client';

swagger_parser/lib/src/generator/model/programming_language.dart

@@ -49,6 +49,7 @@ enum ProgrammingLanguage {
     required bool generateValidator,
     required bool useFreezed3,
     required bool useMultipartFile,
+    required bool dartMappableConvenientWhen,
     String? fallbackUnion,
   }) {
     switch (this) {
@@ -78,11 +79,14 @@ enum ProgrammingLanguage {
                 dataClass,
                 markFileAsGenerated: markFilesAsGenerated,
                 useMultipartFile: useMultipartFile,
+                fallbackUnion: fallbackUnion,
               ),
             JsonSerializer.dartMappable => dartDartMappableDtoTemplate(
                 dataClass,
                 markFileAsGenerated: markFilesAsGenerated,
                 useMultipartFile: useMultipartFile,
+                fallbackUnion: fallbackUnion,
+                dartMappableConvenientWhen: dartMappableConvenientWhen,
               ),
           };
         }