[dart][dart-dio] Add DioError wrapping

• wrap (de)serialization in try/catch and throw a DioError (this uses the new RequestOptions instance) - generic StateError and FormatException are now wrapped in a DioError which makes it clear that they originated from an API call
• this is a new option in the generator wich defaults to true
• no longer generate code for null body data

This is a breaking change with fallback.

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package 
  ./bin/generate-samples.sh
  ./bin/utils/export_docs_generators.sh

  Commit all changed files. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*. For Windows users, please run the script in Git BASH.
• File the PR against the correct branch: master, 5.1.x, 6.0.x
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

CC @swipesight (2018/09) @jaumard (2018/09) @josh-burton (2019/12) @amondnet (2019/12) @sbu-WBT (2020/12) @kuhnroyal (2020/12) @agilob (2020/12)

docs/generators/dart-dio.md

@@ -9,10 +9,11 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|
 |dateLibrary|Option. Date library to use|<dl><dt>**core**</dt><dd>Dart core library (DateTime)</dd><dt>**timemachine**</dt><dd>Time Machine is date and time library for Flutter, Web, and Server with support for timezones, calendars, cultures, formatting and parsing.</dd></dl>|core|
+|dioErrorWrapping|Wrap serialization errors in DioErrors| |true|
 |disallowAdditionalPropertiesIfNotPresent|If false, the 'additionalProperties' implementation (set to true by default) is compliant with the OAS and JSON schema specifications. If true (default), keep the old (incorrect) behaviour that 'additionalProperties' is set to false by default.|<dl><dt>**false**</dt><dd>The 'additionalProperties' implementation is compliant with the OAS and JSON schema specifications.</dd><dt>**true**</dt><dd>Keep the old (incorrect) behaviour that 'additionalProperties' is set to false by default.</dd></dl>|true|
 |ensureUniqueParams|Whether to ensure parameter names are unique in an operation (rename parameters that are not).| |true|
 |legacyDiscriminatorBehavior|Set to true 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|
-|nullableFields|Make all fields nullable in the JSON payload| |null|
+|nullableFields|Make all fields nullable in the JSON payload| |false|
 |prependFormOrBodyParameters|Add form or body parameters to the beginning of the parameter list.| |false|
 |pubAuthor|Author name in generated pubspec| |null|
 |pubAuthorEmail|Email address of the author in generated pubspec| |null|

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

@@ -54,7 +54,7 @@ public class DartClientCodegen extends AbstractDartCodegen {
         super.processOpts();
 
         // handle library not being set
-        if(additionalProperties.get(CodegenConstants.SERIALIZATION_LIBRARY) == null) {
+        if (additionalProperties.get(CodegenConstants.SERIALIZATION_LIBRARY) == null) {
             this.library = SERIALIZATION_LIBRARY_NATIVE;
             LOGGER.debug("Serialization library not set, using default {}", SERIALIZATION_LIBRARY_NATIVE);
         } else {

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

@@ -37,12 +37,22 @@ public class DartDioClientCodegen extends AbstractDartCodegen {
     private final Logger LOGGER = LoggerFactory.getLogger(DartDioClientCodegen.class);
 
     public static final String NULLABLE_FIELDS = "nullableFields";
+    public static final Boolean NULLABLE_FIELDS_DEFAULT = false;
+
+    public static final String DIO_ERROR_WRAPPING = "dioErrorWrapping";
+    public static final Boolean DIO_ERROR_WRAPPING_DEFAULT = true;
+
     public static final String DATE_LIBRARY = "dateLibrary";
+    public static final String DATE_LIBRARY_CORE = "core";
+    public static final String DATE_LIBRARY_TIME_MACHINE = "timemachine";
+    public static final String DATE_LIBRARY_DEFAULT = DATE_LIBRARY_CORE;
 
     private static final String CLIENT_NAME = "clientName";
 
-    private boolean nullableFields = false;
-    private String dateLibrary = "core";
+    private boolean nullableFields;
+    private boolean dioErrorWrapping;
+    private String dateLibrary;
+    private String clientName;
 
     public DartDioClientCodegen() {
         super();
@@ -50,13 +60,17 @@ public class DartDioClientCodegen extends AbstractDartCodegen {
         embeddedTemplateDir = "dart-dio";
         this.setTemplateDir(embeddedTemplateDir);
 
-        cliOptions.add(new CliOption(NULLABLE_FIELDS, "Make all fields nullable in the JSON payload"));
-        CliOption dateLibrary = new CliOption(DATE_LIBRARY, "Option. Date library to use").defaultValue(this.getDateLibrary());
-        Map<String, String> dateOptions = new HashMap<>();
-        dateOptions.put("core", "Dart core library (DateTime)");
-        dateOptions.put("timemachine", "Time Machine is date and time library for Flutter, Web, and Server with support for timezones, calendars, cultures, formatting and parsing.");
-        dateLibrary.setEnum(dateOptions);
-        cliOptions.add(dateLibrary);
+        cliOptions.add(CliOption.newBoolean(NULLABLE_FIELDS, "Make all fields nullable in the JSON payload", NULLABLE_FIELDS_DEFAULT));
+        cliOptions.add(CliOption.newBoolean(DIO_ERROR_WRAPPING, "Wrap serialization errors in DioErrors", DIO_ERROR_WRAPPING_DEFAULT));
+        final CliOption dateOption = new CliOption(DATE_LIBRARY, "Option. Date library to use");
+        dateOption.setDefault(DATE_LIBRARY_DEFAULT);
+        dateOption.setType("String");
+
+        final Map<String, String> dateOptions = new HashMap<>();
+        dateOptions.put(DATE_LIBRARY_CORE, "Dart core library (DateTime)");
+        dateOptions.put(DATE_LIBRARY_TIME_MACHINE, "Time Machine is date and time library for Flutter, Web, and Server with support for timezones, calendars, cultures, formatting and parsing.");
+        dateOption.setEnum(dateOptions);
+        cliOptions.add(dateOption);
 
         typeMapping.put("Array", "BuiltList");
         typeMapping.put("array", "BuiltList");
@@ -94,7 +108,7 @@ public class DartDioClientCodegen extends AbstractDartCodegen {
         this.dateLibrary = library;
     }
 
-    public boolean getNullableFields() {
+    public boolean isNullableFields() {
         return nullableFields;
     }
 
@@ -102,6 +116,22 @@ public class DartDioClientCodegen extends AbstractDartCodegen {
         this.nullableFields = nullableFields;
     }
 
+    public boolean isDioErrorWrapping() {
+        return dioErrorWrapping;
+    }
+
+    public void setDioErrorWrapping(boolean dioErrorWrapping) {
+        this.dioErrorWrapping = dioErrorWrapping;
+    }
+
+    public String getClientName() {
+        return clientName;
+    }
+
+    public void setClientName(String clientName) {
+        this.clientName = clientName;
+    }
+
     @Override
     public String getName() {
         return "dart-dio";
@@ -157,23 +187,25 @@ public class DartDioClientCodegen extends AbstractDartCodegen {
             LOGGER.info("NOTE: To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI).");
         }
 
-        if (additionalProperties.containsKey(NULLABLE_FIELDS)) {
-            this.setNullableFields(convertPropertyToBooleanAndWriteBack(NULLABLE_FIELDS));
-        } else {
-            //not set, use to be passed to template
-            additionalProperties.put(NULLABLE_FIELDS, nullableFields);
+        if (!additionalProperties.containsKey(NULLABLE_FIELDS)) {
+            additionalProperties.put(NULLABLE_FIELDS, NULLABLE_FIELDS_DEFAULT);
         }
+        setNullableFields(convertPropertyToBooleanAndWriteBack(NULLABLE_FIELDS));
 
-        if (!additionalProperties.containsKey(CLIENT_NAME)) {
-            additionalProperties.put(CLIENT_NAME, org.openapitools.codegen.utils.StringUtils.camelize(pubName));
+        if (!additionalProperties.containsKey(DIO_ERROR_WRAPPING)) {
+            additionalProperties.put(DIO_ERROR_WRAPPING, DIO_ERROR_WRAPPING_DEFAULT);
+        }
+        setDioErrorWrapping(convertPropertyToBooleanAndWriteBack(DIO_ERROR_WRAPPING));
+
+        if (!additionalProperties.containsKey(DATE_LIBRARY)) {
+            additionalProperties.put(DATE_LIBRARY, DATE_LIBRARY_DEFAULT);
         }
+        setDateLibrary(additionalProperties.get(DATE_LIBRARY).toString());
 
-        if (additionalProperties.containsKey(DATE_LIBRARY)) {
-            this.setDateLibrary(additionalProperties.get(DATE_LIBRARY).toString());
+        if (!additionalProperties.containsKey(CLIENT_NAME)) {
+            additionalProperties.put(CLIENT_NAME, org.openapitools.codegen.utils.StringUtils.camelize(pubName));
         }
-        // make api and model doc path available in mustache template
-        additionalProperties.put("apiDocPath", apiDocPath);
-        additionalProperties.put("modelDocPath", modelDocPath);
+        setClientName(additionalProperties.get(CLIENT_NAME).toString());
 
         final String libFolder = sourceFolder + File.separator + "lib";
         supportingFiles.add(new SupportingFile("pubspec.mustache", "", "pubspec.yaml"));
@@ -192,19 +224,27 @@ public class DartDioClientCodegen extends AbstractDartCodegen {
         supportingFiles.add(new SupportingFile("auth/oauth.mustache", authFolder, "oauth.dart"));
         supportingFiles.add(new SupportingFile("auth/auth.mustache", authFolder, "auth.dart"));
 
-        if ("core".equals(dateLibrary)) {
-            // this option uses the same classes as normal dart generator
-            additionalProperties.put("core", "true");
-        } else if ("timemachine".equals(dateLibrary)) {
-            additionalProperties.put("timeMachine", "true");
-            typeMapping.put("date", "OffsetDate");
-            typeMapping.put("Date", "OffsetDate");
-            typeMapping.put("DateTime", "OffsetDateTime");
-            typeMapping.put("datetime", "OffsetDateTime");
-            additionalReservedWords.addAll(Sets.newHashSet("OffsetDate", "OffsetDateTime"));
-            importMapping.put("OffsetDate", "package:time_machine/time_machine.dart");
-            importMapping.put("OffsetDateTime", "package:time_machine/time_machine.dart");
-            supportingFiles.add(new SupportingFile("local_date_serializer.mustache", libFolder, "local_date_serializer.dart"));
+        configureDateLibrary(libFolder);
+    }
+
+    private void configureDateLibrary(String libFolder) {
+        switch (dateLibrary) {
+            case DATE_LIBRARY_TIME_MACHINE:
+                additionalProperties.put("timeMachine", "true");
+                typeMapping.put("date", "OffsetDate");
+                typeMapping.put("Date", "OffsetDate");
+                typeMapping.put("DateTime", "OffsetDateTime");
+                typeMapping.put("datetime", "OffsetDateTime");
+                additionalReservedWords.addAll(Sets.newHashSet("OffsetDate", "OffsetDateTime"));
+                importMapping.put("OffsetDate", "package:time_machine/time_machine.dart");
+                importMapping.put("OffsetDateTime", "package:time_machine/time_machine.dart");
+                supportingFiles.add(new SupportingFile("local_date_serializer.mustache", libFolder, "local_date_serializer.dart"));
+                break;
+            default:
+            case DATE_LIBRARY_CORE:
+                // this option uses the same classes as normal dart generator
+                additionalProperties.put("core", "true");
+                break;
         }
     }
 

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

@@ -78,6 +78,15 @@ public class CodegenOperation {
         return nonempty(bodyParams);
     }
 
+    /**
+     * Check if there's at least one body parameter or at least one form parameter
+     *
+     * @return true if body or form parameter exists, false otherwise
+     */
+    public boolean getHasBodyOrFormParams() {
+        return getHasBodyParam() || getHasFormParams();
+    }
+
     /**
      * Check if there's at least one query parameter
      *

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

@@ -71,64 +71,93 @@ class {{classname}} {
       onSendProgress: onSendProgress,
       onReceiveProgress: onReceiveProgress,
     );
+    {{#hasBodyOrFormParams}}
 
     dynamic _bodyData;
-    {{#hasFormParams}}
 
-    _bodyData = {{#isMultipart}}FormData.fromMap({{/isMultipart}}<String, dynamic>{
-      {{#formParams}}
-      {{^required}}{{^nullable}}if ({{{paramName}}} != null) {{/nullable}}{{/required}}r'{{{baseName}}}': {{#isFile}}MultipartFile.fromBytes({{{paramName}}}, filename: r'{{{baseName}}}'){{/isFile}}{{^isFile}}parameterToString(_serializers, {{{paramName}}}){{/isFile}},
-      {{/formParams}}
-    }{{#isMultipart}}){{/isMultipart}};
-    {{/hasFormParams}}
-    {{#bodyParam}}
-
-    {{#isPrimitiveType}}
-    _bodyData = {{paramName}};
-    {{/isPrimitiveType}}
-    {{^isPrimitiveType}}
-    {{#isContainer}}
-    const _type = FullType(Built{{#isMap}}Map{{/isMap}}{{#isArray}}{{#uniqueItems}}Set{{/uniqueItems}}{{^uniqueItems}}List{{/uniqueItems}}{{/isArray}}, [{{#isMap}}FullType(String), {{/isMap}}FullType({{{baseType}}})]);
-    _bodyData = _serializers.serialize({{paramName}}, specifiedType: _type);
-    {{/isContainer}}
-    {{^isContainer}}
-    const _type = FullType({{{baseType}}});
-    _bodyData = _serializers.serialize({{paramName}}, specifiedType: _type);
-    {{/isContainer}}
-    {{/isPrimitiveType}}
-    {{/bodyParam}}
+    try {
+      {{#hasFormParams}}
+      _bodyData = {{#isMultipart}}FormData.fromMap({{/isMultipart}}<String, dynamic>{
+        {{#formParams}}
+        {{^required}}{{^nullable}}if ({{{paramName}}} != null) {{/nullable}}{{/required}}r'{{{baseName}}}': {{#isFile}}MultipartFile.fromBytes({{{paramName}}}, filename: r'{{{baseName}}}'){{/isFile}}{{^isFile}}parameterToString(_serializers, {{{paramName}}}){{/isFile}},
+        {{/formParams}}
+      }{{#isMultipart}}){{/isMultipart}};
+      {{/hasFormParams}}
+      {{#bodyParam}}
+      {{#isPrimitiveType}}
+      _bodyData = {{paramName}};
+      {{/isPrimitiveType}}
+      {{^isPrimitiveType}}
+      {{#isContainer}}
+      const _type = FullType(Built{{#isMap}}Map{{/isMap}}{{#isArray}}{{#uniqueItems}}Set{{/uniqueItems}}{{^uniqueItems}}List{{/uniqueItems}}{{/isArray}}, [{{#isMap}}FullType(String), {{/isMap}}FullType({{{baseType}}})]);
+      _bodyData = _serializers.serialize({{paramName}}, specifiedType: _type);
+      {{/isContainer}}
+      {{^isContainer}}
+      const _type = FullType({{{baseType}}});
+      _bodyData = _serializers.serialize({{paramName}}, specifiedType: _type);
+      {{/isContainer}}
+      {{/isPrimitiveType}}
+      {{/bodyParam}}
+    } catch(error) {
+      {{#dioErrorWrapping}}
+      throw DioError(
+        request: _request,
+        type: DioErrorType.DEFAULT,
+        error: error,
+      );
+      {{/dioErrorWrapping}}
+      {{^dioErrorWrapping}}
+      rethrow;
+      {{/dioErrorWrapping}}
+    }
+    {{/hasBodyOrFormParams}}
 
     final _response = await _dio.request<dynamic>(
-      _request.path,
-      data: _bodyData,
+      _request.path,{{#hasBodyOrFormParams}}
+      data: _bodyData,{{/hasBodyOrFormParams}}
       options: _request,
     );
     {{#returnType}}
 
-    {{#isResponseFile}}
-    final {{{returnType}}} _responseData = _response.data;
-    {{/isResponseFile}}
-    {{^isResponseFile}}
-    {{#returnSimpleType}}
-    {{#returnTypeIsPrimitive}}
-    final {{{returnType}}} _responseData = _response.data as {{{returnType}}};
-    {{/returnTypeIsPrimitive}}
-    {{^returnTypeIsPrimitive}}
-    const _responseType = FullType({{{returnType}}});
-    final _responseData = _serializers.deserialize(
-      _response.data,
-      specifiedType: _responseType,
-    ) as {{{returnType}}};
-    {{/returnTypeIsPrimitive}}
-    {{/returnSimpleType}}
-    {{^returnSimpleType}}
-    const _responseType = FullType(Built{{#isArray}}{{#uniqueItems}}Set{{/uniqueItems}}{{^uniqueItems}}List{{/uniqueItems}}{{/isArray}}{{#isMap}}Map{{/isMap}}, [{{#isMap}}FullType(String), {{/isMap}}FullType({{{returnBaseType}}})]);
-    final {{{returnType}}} _responseData = _serializers.deserialize(
-      _response.data,
-      specifiedType: _responseType,
-    ) as {{{returnType}}};
-    {{/returnSimpleType}}
-    {{/isResponseFile}}
+    {{{returnType}}} _responseData;
+    try {
+      {{#isResponseFile}}
+      _responseData = _response.data;
+      {{/isResponseFile}}
+      {{^isResponseFile}}
+      {{#returnSimpleType}}
+      {{#returnTypeIsPrimitive}}
+      _responseData = _response.data as {{{returnType}}};
+      {{/returnTypeIsPrimitive}}
+      {{^returnTypeIsPrimitive}}
+      const _responseType = FullType({{{returnType}}});
+      _responseData = _serializers.deserialize(
+        _response.data,
+        specifiedType: _responseType,
+      ) as {{{returnType}}};
+      {{/returnTypeIsPrimitive}}
+      {{/returnSimpleType}}
+      {{^returnSimpleType}}
+      const _responseType = FullType(Built{{#isArray}}{{#uniqueItems}}Set{{/uniqueItems}}{{^uniqueItems}}List{{/uniqueItems}}{{/isArray}}{{#isMap}}Map{{/isMap}}, [{{#isMap}}FullType(String), {{/isMap}}FullType({{{returnBaseType}}})]);
+      _responseData = _serializers.deserialize(
+        _response.data,
+        specifiedType: _responseType,
+      ) as {{{returnType}}};
+      {{/returnSimpleType}}
+      {{/isResponseFile}}
+    } catch (error) {
+      {{#dioErrorWrapping}}
+      throw DioError(
+        request: _request,
+        response: _response,
+        type: DioErrorType.DEFAULT,
+        error: error,
+      );
+      {{/dioErrorWrapping}}
+      {{^dioErrorWrapping}}
+      rethrow;
+      {{/dioErrorWrapping}}
+    }
 
     return Response<{{{returnType}}}>(
       data: _responseData,