Recognize webhooks in the top-level structure check
What
OpenAPI 3.1.0 requires at least one of paths, components or webhooks to exist at the top level of a document: a specification describing only webhooks, or only reusable components, is valid. The structural check (added for #190) already covers the paths/components pair, but it had no awareness of webhooks, so a valid webhooks-only document was reported as an error:
*ERROR* Section: OpenAPI: 'paths,components' -> Should have at least one of paths or components
The check now also treats the document as non-empty when webhooks are declared, and the message names the three alternatives:
$ openapi-style-validator-cli -s webhooksOnly.yaml # a 3.1 document with webhooks and no paths/components
There are no style errors in this spec.
$ openapi-style-validator-cli -s emptyStructure.yaml # no paths, no components, no webhooks
*ERROR* Section: OpenAPI: 'paths,components,webhooks' -> Should have at least one of paths, components or webhooks
Why
The specification makes webhooks a first alternative to paths and components, but the validator had no awareness of it (#93), so valid webhooks-only documents failed the structural check.
How
- one caveat drove the implementation: the MicroProfile OpenAPI API the library is built against (3.1) declares no
webhooksaccessor on the document model, and the CLI, Gradle and Maven plugins convert parsed specifications through empoa-swagger-core, whose wrapper (SwOpenAPI) keeps the swagger model - which does carrywebhooks- behind itsgetSw()accessor. The webhooks are therefore read reflectively: first throughgetWebhooks()when the model provides it (e.g. a MicroProfile OpenAPI 4.0 implementation), then through the swagger model behind an empoa wrapper, and a model exposing neither is considered to have no webhooks. Once the MicroProfile OpenAPI dependency is aligned with OAS 3.1 (#798), the first lookup handles it directly - the lookup is version-agnostic by design, like the rest of this check: it is a lenient presence test (an empty
pathsobject already counts as present since #190), and an emptywebhooksobject counts as present too - what is reported is a document that declares none of the three at all - the error message now names the three alternatives; the check itself remains always-on, since flagging a document with no content at all is never noisy (no new option, same reasoning as #813)
Tests
lib module (plain @Test):
- paths only / components only keep passing (existing tests)
- webhooks only -> clean, through both a model exposing
getWebhooks()(the way an OAS 3.1-aware model, e.g. MicroProfile OpenAPI 4.0, does) and a wrapper hiding it behindgetSw()(the empoa-swagger-core contract) - an empty
webhooksmap counts as present, consistently withpaths - none of the three -> flagged with the exact new message
ErrorAggregatorTestcovers the renamed aggregator method
cli module (end-to-end):
- a webhooks-only 3.1 spec passes validation with the default options, exercising the real parse -> empoa conversion -> reflective read chain
./gradlew build -x :openapi-style-validator-gradle-plugin:functionalTest is green with JDK 21 (the exclusion is the known Gradle 7.6 vs JDK 21 incompatibility of that task on dev machines; upstream CI runs it).
Fixes #93
Summary by cubic
Fixes the top-level structure check so valid OpenAPI 3.1 documents declaring only webhooks (or only reusable components) no longer fail with a false "missing paths or components" error. The check now requires at least one of paths, components, or webhooks, and the error message names all three.
Implementation notes
- Webhooks are read reflectively because the MicroProfile OpenAPI 3.1 API this library builds against has no
webhooksaccessor: the lookup triesgetWebhooks()first, then the swagger model behind an empoa-swagger-core wrapper, matching how the CLI, Gradle and Maven plugins parse documents. A missing swagger model is treated as having no webhooks. - An empty
webhooksobject counts as present, consistent withpathsandcomponents.