#24037 [openapi, openapi-yaml] feature - add sortOutput option to deterministically sort paths and schemas, http methods, etc...

Add a new 'sortOutput' generator option to the 'openapi' (JSON) and 'openapi-yaml' (YAML) documentation generators that produces a deterministically ordered spec:

• Paths are sorted alphabetically by URL
• Schemas, parameters, requestBodies, responses, headers, examples, links, callbacks and securitySchemes are sorted alphabetically by name
• HTTP methods within each path are ordered by the classical convention: GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, TRACE

Implementation details:

• OpenAPISorter: replaces Paths and all Components maps with TreeMaps
• PathItemSerializer: custom Jackson serializer writing operations in classical HTTP method order (only registered when sortOutput=true)
• SerializerUtils: overloaded toJsonString/toYamlString with sortOutput flag; createModule(boolean) registers PathItemSerializer when true
• OpenAPIGenerator / OpenAPIYamlGenerator: wire the new option through to the serializer

PR checklist

• Read the contribution guidelines.
• 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 WSL)
  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.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

---

Summary by cubic

Adds a sortOutput option to openapi and openapi-yaml for deterministic JSON/YAML output (sorted paths, components, and HTTP method order) to reduce noisy diffs. Docs were refined, forbidden method calls removed, and tests added.

• New Features

  • sortOutput (default: false) in both generators.
  • Paths sorted A–Z; component maps by key; HTTP methods ordered: GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, TRACE.
  • Implemented via OpenAPISorter and a custom PathItemSerializer; CLI option added; docs updated and clarified; tests verify JSON and YAML ordering.

• Migration

  • Disabled by default. Enable with -p sortOutput=true.
  • No functional spec changes; only output ordering.