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

[khayashi4337]

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 when they refer to a path-item member, so nested typos aren't misreported as dropped operations.
• Keeps the --skip-validate-spec contract: generation still proceeds when only unrecognized attributes are present.
• Leaves the default SpecValidationException path unchanged.
• Adds regression tests for the warning, false positives, null-spec failure, and default validation.

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

[cubic-dev-ai]

2 issues found across 5 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/resources/3_0/issue_24212_path_item_parameter_typo.yaml">

<violation number="1" location="modules/openapi-generator/src/test/resources/3_0/issue_24212_path_item_parameter_typo.yaml:10">
P3: The misspelled `requried` (instead of `required`) is the entire point of this fixture: it makes swagger-parser emit a nested unexpected-attribute message that the fix must not classify as a dropped path-item member. Nothing in the file says this, so a future "fix the typo" change would silently neuter the regression test: with the correct `required` key the parser emits no unexpected-attribute message, no validation message reaches the new detection branch, and `shouldNotFalsePositiveOnNestedPathItemMemberTypo` passes vacuously while the false-positive case it guards goes untested. Add a comment on or above this line explaining that the typo is intentional and what it exercises.</violation>
</file>

<file name="modules/openapi-generator/src/main/java/org/openapitools/codegen/config/CodegenConfigurator.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/config/CodegenConfigurator.java:68">
P2: When an unexpected nested property follows a quoted key, this greedy path group treats the entire nested prefix as the path and reports that property as a dropped path-item member. Restrict the path capture to the actual quoted path segment so nested diagnostics do not produce misleading `MISSING` warnings.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When an unexpected nested property follows a quoted key, this greedy path group treats the entire nested prefix as the path and reports that property as a dropped path-item member. Restrict the path capture to the actual quoted path segment so nested diagnostics do not produce misleading MISSING warnings.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/java/org/openapitools/codegen/config/CodegenConfigurator.java, line 68:

<comment>When an unexpected nested property follows a quoted key, this greedy path group treats the entire nested prefix as the path and reports that property as a dropped path-item member. Restrict the path capture to the actual quoted path segment so nested diagnostics do not produce misleading `MISSING` warnings.</comment>

<file context>
@@ -57,6 +59,14 @@ public class CodegenConfigurator {
+    // path-level parameter or server object), which is reported under the same "paths.'X'." prefix
+    // but is not itself a dropped operation.
+    private static final Pattern UNEXPECTED_PATH_ITEM_ATTRIBUTE =
+            Pattern.compile("attribute paths\\.'(.+)'\\.([^.\\[\\]()'\\s]+) is unexpected");
+
     private GeneratorSettings.Builder generatorSettingsBuilder = GeneratorSettings.newBuilder();
</file context>

Suggested change

	Pattern.compile("attribute paths\\.'(.+)'\\.([^.\\[\\]()'\\s]+) is unexpected");
	Pattern.compile("attribute paths\\.'([^']*)'\\.([^.\\[\\]()'\\s]+) is unexpected");

[cubic-dev-ai]

P3: The misspelled requried (instead of required) is the entire point of this fixture: it makes swagger-parser emit a nested unexpected-attribute message that the fix must not classify as a dropped path-item member. Nothing in the file says this, so a future "fix the typo" change would silently neuter the regression test: with the correct required key the parser emits no unexpected-attribute message, no validation message reaches the new detection branch, and shouldNotFalsePositiveOnNestedPathItemMemberTypo passes vacuously while the false-positive case it guards goes untested. Add a comment on or above this line explaining that the typo is intentional and what it exercises.

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/resources/3_0/issue_24212_path_item_parameter_typo.yaml, line 10:

<comment>The misspelled `requried` (instead of `required`) is the entire point of this fixture: it makes swagger-parser emit a nested unexpected-attribute message that the fix must not classify as a dropped path-item member. Nothing in the file says this, so a future "fix the typo" change would silently neuter the regression test: with the correct `required` key the parser emits no unexpected-attribute message, no validation message reaches the new detection branch, and `shouldNotFalsePositiveOnNestedPathItemMemberTypo` passes vacuously while the false-positive case it guards goes untested. Add a comment on or above this line explaining that the typo is intentional and what it exercises.</comment>

<file context>
@@ -0,0 +1,17 @@
+    parameters:
+      - name: id
+        in: path
+        requried: true
+        schema:
+          type: string
</file context>

Suggested change

	requried: true
	# intentional typo: swagger-parser reports `attribute paths.'/tasks/{id}'.parameters.0.requried is unexpected`,
	# which is a nested key and must NOT be flagged as a dropped path-item operation (issue #24212)
	requried: true

[wing328]

thanks for the PR. please review the feedback from cubic-dev-ai when you've time.

cc @OpenAPITools/generator-core-team