Fix: Resolve Dart 3.5+ and json_serializable 6.9.0+ compatibility issues in generated dart-dio clients

[mikefaille]

This commit fixes compatibility problems between the generated dart-dio code, json_serializable 6.9.0+, and Dart SDK 3.5 or later.

Changes:

• Updated pubspec.mustache:
  • Set the minimum SDK constraint for the generated package to >=3.5.0 <4.0.0, reflecting the language version used in the generated code.
  • Bump json_annotation dependency to ^4.9.0.
  • Bump json_serializable dependency to ^6.9.0.

These changes ensure that the generated code:

• Is compatible with json_serializable 6.9.0+ and Dart SDK 3.5+.
• Avoids Dart 3.5+ specific syntax that causes errors on older SDKs.
• Maintains existing functionality and type safety.

@jaumard (2018/09) @josh-burton (2019/12) @amondnet (2019/12) @sbu-WBT (2020/12) @kuhnroyal (2020/12) @agilob (2020/12) @ahmednfwela (2021/08)

PS: This minor fix has been merged into master as it's a non-breaking change targeting the upcoming 7.x.0 minor release. json_serializable 6.9.0+ mandates a minimum Dart SDK of 3.5 due to its use of newer language features. Consequently, generated dart-dio clients now also require Dart SDK 3.5 or higher. Existing projects using Dart 3.0 and higher should not be impacted because this update maintains backward compatibility for the generated code's public API and serialization format. This change primarily ensures compatibility with newer projects and going forward, which often do not support older Dart versions.

Resolves: #16117, #14863

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 || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in Git BASH)
  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*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• [ 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.

[mikefaille]

Thoroughly tested with a complex and large OpenAPI specification : https://github.com/twilio/twilio-oai/blob/main/spec/json/twilio_api_v2010.json

[mikefaille]

I redo my commit. Few min.

[mikefaille]

Done. It's ready.

[mikefaille]

I was trying out the new merge feature on this PR, but the whole PR ran into a block. Switched back to the standard merge process. Please let me know if you have any questions so we can get this PR merged.

[wing328]

just merged it. thanks again for the PR

[kuhnroyal]

Sadly I think this is not a good change. Bumping all these dependencies is unnecessary and potentially forces library consumers into updates of other dependencies.
Nothing prevented the use with Dart 3.5 & json_serializable 6.9.+ but now it forces it.

[mikefaille]

@kuhnroyal Thanks for the feedback. I understand the concern about forced upgrades. However, the statement that "nothing prevented the use with Dart 3.5 & json_serializable 6.9.+" is factually incorrect. The previous configuration wasn't permissive; it was flawed. json_serializable 6.9.+ requires Dart 3.5+, a dependency the old generator template (allowing <4.0.0) failed to enforce. This created a hidden incompatibility, leading to obscure runtime errors)l, not a clear indication of needing to upgrade (refer to the linked issues for details.).

This PR doesn't introduce a new restriction; it enforces an existing one. The choice isn't between "keeping the project as is" and "progress." The "as is" option is broken – it relies on an outdated OpenAPI Generator version with incorrect SDK constraints. It seems to work with Dart 2.x only because of that flawed configuration. Trying to use that setup with newer libraries and/or a Dart SDK below 3.5 will cause errors. This goes against keeping dependencies updated, and against Dart's recommendation to use newer versions. Because the Dart website currently recommends version 3.7.0 as the stable version for new projects, the previous OpenAPI Generator configuration would not have worked correctly for any new project.

We get a clear error message requiring Dart 3.5+ now, a vast improvement. Communicating this is a priority. The effort to maintain an unsupported Dart 2.x receiving no updates since Dart 3 alpha is greater than the benefits of a current setup. Upgrading within Dart 3.x is straightforward. Projects that can't upgrade can use older generator versions, and their existing code will function. This change prioritizes correctness and maintainability.

[kuhnroyal]

I understand now that this is mainly a build_runner limitation and why it was a problem for fresh projects.

But there are still projects that work with combinations of sdk: >=3.0.0 <3.5.0 and json_serializable: >=6.x <6.9.0 that might now be unable to update.

I am always conflicted between supporting these or dropping them.

[wing328]

But there are still projects that work with combinations of sdk: >=3.0.0 <3.5.0 and json_serializable: >=6.x <6.9.0 that might now be unable to update.

let's see if anyone has a valid use case with this and we can add an option for fallback accordingly.