feat(openapi, openapi-yaml): add sortOutput option

[Picazsoo]

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 the openapi and openapi-yaml generators to produce deterministic specs. Paths and components are sorted, and HTTP methods are written in a standard order to reduce noisy diffs.

• New Features

  • sortOutput (default: false) for openapi and openapi-yaml.
  • Paths sorted A–Z; components sorted by key (schemas, parameters, requestBodies, responses, headers, examples, links, callbacks, securitySchemes).
  • HTTP methods ordered: GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, TRACE.

• Migration

  • Disabled by default. Enable with -p sortOutput=true (or via additionalProperties).
  • No spec changes; only output ordering.

^{Written for commit fbef10f. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 8 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/test/java/org/openapitools/codegen/yaml/YamlGeneratorTest.java">

<violation number="1" location="modules/openapi-generator/src/test/java/org/openapitools/codegen/yaml/YamlGeneratorTest.java:231">
P2: indexOf-based ordering tests silently pass when expected operations are missing due to -1 comparison</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: indexOf-based ordering tests silently pass when expected operations are missing due to -1 comparison

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/test/java/org/openapitools/codegen/yaml/YamlGeneratorTest.java, line 231:

<comment>indexOf-based ordering tests silently pass when expected operations are missing due to -1 comparison</comment>

<file context>
@@ -185,4 +185,55 @@ public void testIssue19929() throws Exception {
+
+        // HTTP method order — GET before POST in /zebra (spec has POST first)
+        int zebraBlock = yaml.indexOf("/zebra:");
+        Assert.assertTrue(yaml.indexOf("get:", zebraBlock) < yaml.indexOf("post:", zebraBlock),
+                "GET must appear before POST within /zebra");
+
</file context>