fix(core): warn instead of silently dropping unrecognized path-item operations (#24212)

Merged
KH
23d ago
+270-0

What

Under --skip-validate-spec, when the OpenAPI parser encounters a path-item member it doesn't recognize (e.g. a future operation like OpenAPI 3.2's query HTTP method), it silently drops it. Generation exits 0 with a success message, but the operation is simply absent from the generated output — the only trace is a generic "There were issues with the specification" WARN that doesn't say anything about code being missing.

This PR makes that failure mode loud instead of silent:

  • Detects swagger-parser's attribute paths.'X'.Y is unexpected validation messages and, when generation is actually going to proceed, escalates matching ones into an explicit WARN naming exactly which path-item member(s) will be missing from the generated output.
  • When the parser cannot produce an OpenAPI object at all (e.g. because the spec declares a version newer than the parser supports), toContext() now fails immediately with a message that includes the parser's own diagnostics, instead of letting null silently propagate through Context → ClientOptInput → DefaultGenerator before a generic error surfaces later.

Closes #24212.

Why not always hard-fail?

--skip-validate-spec exists specifically to let generation continue despite spec issues, so this keeps that contract: generation still succeeds when only unrecognized attributes are present, it just now says so clearly instead of staying silent. When the parser can't produce a document at all, there's nothing to generate from regardless of the flag, so that case fails fast with a clear reason.

Testing

  • Added 4 unit tests to CodegenConfiguratorTest (new resource specs under src/test/resources/3_0/issue_24212_*.yaml) covering: the warning fires for a genuinely dropped operation, it does not false-positive on an unrelated typo nested inside a path-level parameters/servers object, the null-spec case fails with a clear message and no misleading "MISSING" warning, and the pre-existing default (non-skip) SpecValidationException path is unchanged.
  • Manually verified against the issue's own repro spec and several hand-crafted edge cases (nested parameter typo, path-level server typo, OpenAPI 3.2 version).
  • Ran ./bin/generate-samples.sh (all 803 configs) and ./bin/utils/export_docs_generators.sh per the PR checklist — zero diff, confirming this change doesn't alter any existing generator output.

Summary by cubic

Fixes #24212 so --skip-validate-spec no longer silently drops unrecognized path-item operations like OpenAPI 3.2's query. It now warns with the exact paths and members that will be missing, and fails fast with parser diagnostics when the parser can't produce an OpenAPI object at all.

Bug Fixes

  • Detects swagger-parser's attribute paths.'X'.Y is unexpected messages only for single-quoted path names with a simple member token, so neither nested typos nor quoted path templates are misreported as dropped operations.
  • Keeps the --skip-validate-spec contract: generation still proceeds when only unrecognized attributes are present, and the default SpecValidationException path is unchanged.
  • Adds regression tests for the warning, both false-positive shapes, null-spec failure, and default validation.