Fix #858: don't report identical schemas as changed when only the OpenAPI version differs
Fixes #858
What
Comparing two specs that differ only in the openapi version field (3.0.1 vs 3.1.0, as attached in the issue) reported every operation as changed with bogus parameter type changes and flipped the verdict to INCOMPATIBLE.
Why
For OpenAPI 3.1 documents the parser (swagger-parser 2.1.31 / swagger-models 2.2.34) stores the type keyword in the JSON Schema 2020-12 types set and leaves Schema.getType() null, while OpenAPI 3.0 documents expose the same keyword only through Schema.getType(). The schema comparison uses the singular type, so each identical schema compared across the version boundary looked like a string -> null type change (a type change is backward-incompatible, which is why the whole report turned red).
How
Before diffing, when exactly one side of the comparison is an OpenAPI 3.1 document, a new document walker (SchemaTypeNormalizer) mirrors a single-element types set back into the singular type keyword — a lossless representation swap. Sets with zero or multiple types are left untouched, and same-version comparisons are unchanged, so this only removes the cross-version false positives.
This is deliberately kept out of SchemaDiff/SchemaDiffResult/ChangedSchema so it does not conflict with the other open 3.1-comparison PRs (#938, #962, #963).
Tests
New Issue858Test (regression pair taken from the issue's attached specs, tested in both directions plus the overall unchanged verdict):
- fails on unpatched master (
594183e) — 3/3 red, reproducing the issue, - passes with this change —
no_changesin both directions.
Full mvn verify is green (core: 273 tests, cli: 13 tests).
Summary by cubic
Fixes #858 — comparing two specs that differ only in the openapi version field (3.0.1 vs 3.1.0) previously reported every operation as changed and flipped the verdict to INCOMPATIBLE.
The parser stores the type keyword in the JSON Schema 2020-12 types set for 3.1 documents and leaves Schema.getType() null, while 3.0 documents expose it only through getType(). When exactly one side is a 3.1 document, the new SchemaTypeNormalizer now mirrors single-element types sets back into the singular type before diffing. Sets with zero or multiple types are left untouched, and same-version comparisons are unchanged.
Adds a regression test using the specs from the issue, verified in both directions.