Recognize webhooks in the top-level structure check

IN
18h ago
+184-6

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 webhooks accessor 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 carry webhooks - behind its getSw() accessor. The webhooks are therefore read reflectively: first through getWebhooks() 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 paths object already counts as present since #190), and an empty webhooks object 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 behind getSw() (the empoa-swagger-core contract)
  • an empty webhooks map counts as present, consistently with paths
  • none of the three -> flagged with the exact new message
  • ErrorAggregatorTest covers 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 webhooks accessor: the lookup tries getWebhooks() 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 webhooks object counts as present, consistent with paths and components.