[dart][dart-dio] Improve API code & wrap serialization errors

Background

Currently during (de)serialization errors, four types of exceptions can be thrown:

• StateError - during (de)serialization when built_value can not find a matching serializer (very generic dart:core error, can be thrown from almost anything)
• FormatException - json.decode failed (very generic dart:core error, can be thrown from almost anything)
• JsonUnsupportedObjectError - json.encode failed
• DeserializationError - built_value deserialization failed

When implementing a general error handling in a consuming Dart application it is not clear that these errors are thrown by the API client as most of these can be thrown from other sources, especially when using built_value for other things as well.

By default when using dio with plain json.encode/decode all (de)serialization exceptions would be wrapped in DioError instances but since our built_value (de)serialization occurs before/after the dio call this is not the case.

The errors need to be manually wrapped in a DioError instance. To achieve this the API method call code has to be restructured:

• first construct a RequestOptions instance with all parameters etc. inline (this can be used to fill the DioError in case of serialization failure)
• then construct and serialize the body data
• then send the request and await the response
• then deserialize the response
• always use the specifiedType for built_value (de)serialization instead of a mix of ways (this does the same as finding the serializer directly)
• wrap (de)serialization in try/catch and throw a DioError (this uses the new RequestOptions and possible the response instances) - generic errors are now wrapped in a DioError which makes it clear that they originated from serialization code inside an API call

Breaking change

The API call signature doesn't change but the type of thrown errors changes. For users who are checking for those errors it could be a breaking change.

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.