["Soft" Breaking Change] Remove defunct global property withXml from generator, docs, maven & gradle plugin

[Philzen]

Users of the plugins can just delete it (b/c the setting never transpired through to the actual generator), or move it into configOptions (given the generator supports XML, you can enable it this way) should they choose so.

---

Closes #3839, #5764, and probably also #8902 and #11578.

The basic issue is that withXml is documented as a global property on the main web site as well as the maven plugin. However, no matter what value is provided, Spring or Java generators won't generate XML-related annotations (only when supplying it as a configOption), rendering it effectively useless.

This PR applies the global property to the CodeGen's additionalProperties – if (and only if) it not already defined via --additionalProperties (being a <configOption> in the maven plugin respectively).

Or as a config matrix:

Before

	not provided as add. prop. / <configOption>	--additional-properties withXml=false	--additional-properties withXml=true
not provided as global prop.	❌	❌	✔️
--global-property withXml=false	❌	❌	✔️
--global-property withXml=true	❌ ❗	❌	✔️

After

	not provided as add. prop. / <configOption>	--additional-properties withXml=false	--additional-properties withXml=true
not provided as global prop.	❌	❌	✔️
--global-property withXml=false	❌	❌	✔️
--global-property withXml=true	✔️ 👌	❌	✔️

---

Also fixes the maven plugin description for withXml.

Looking at d609893, i realized that many test cases generate files that they don't test against, so that was just a small optimization (that brought down the execution time for all tests in that file by ~20 % on my machine). Maybe out of scope and can be cherry-picked somewhere else if desired, however i realize there is a lot of potential here to bring down the test suite execution time overall.

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

  (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.1.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

[Philzen]

... of course, another option would be to remove withXml completely from the global options – which would lead to less code instead of more here, and at the end of the day, the generator implementation determines whether it does have any effect at all.

[wing328]

thanks for the PR.

when you've time this week, can you please PM me via Slack?

https://join.slack.com/t/openapi-generator/shared_invite/zt-12jxxd7p2-XUeQM~4pzsU9x~eGLQqX2g

[wing328]

The basic issue is that withXml is documented as a global property on the main web site as well as the maven plugin. However, no matter what value is provided, Spring or Java generators won't generate XML-related annotations (only when supplying it as a configOption), rendering it effectively useless.

my take is to remove withXml from the global option and added it as a generator option instead to the generators that support XML payload.

[Philzen]

my take is to remove withXml from the global option and added it as a generator option instead to the generators that support XML payload.

Fully agreed – the best code is code that can be deleted, meaning less complexity. Will rebase and commit the removal on top of my existing changes.

[Philzen]

@wing328 Ready – realising this is a breaking change, i now rebased this against the 8.0.x branch. A couple of considerations arose on my side regarding this:

• i realised there are >100 commits in master that have not gone into 8.0.x yet. Is there going to be a rebase for that anytime soon? Wondering what the official process here is (ie. shouldn't any PRs against master be immediately also picked into 8.0.x?)
• if this goes into 8.x, maybe i should file a PR for master first that formally deprecates any withXml option, so we have a smoother transition? Of course, in that case we should hold this PR until that is merged and 8.0.x is rebased on master to get a clean removal.