Skip to content

Recognize webhooks in the top-level structure check - #816

Open
Inf1mum wants to merge 2 commits into
OpenAPITools:masterfrom
Inf1mum:fix/93-webhooks-structure
Open

Inf1mum wants to merge 2 commits into
OpenAPITools:masterfrom
Inf1mum:fix/93-webhooks-structure

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 15, 2026 •

Copy link
Copy Markdown

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 (Bump org.eclipse.microprofile.openapi:microprofile-openapi-api from 3.1.1 to 4.0.2 #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 Fails when document doesn't contain paths #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 Validate that the license url and identifier are not both set #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.

Written for commit 4a4eb73. Summary will update on new commits.

View guided diff

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 flagged documents that declare neither `paths` nor
`components` without considering `webhooks`, so a webhooks-only
document was reported in error. The check now also treats the document
as non-empty when webhooks are declared, and the message names the
three alternatives.

The MicroProfile OpenAPI API the library is built against (3.1)
declares no `webhooks` accessor, so webhooks are read reflectively:
through `getWebhooks()` when the model provides it (e.g. a
MicroProfile OpenAPI 4.0 implementation), then through the swagger
model behind an empoa-swagger-core wrapper (the path taken by the CLI,
Gradle and Maven plugins); a model exposing neither is considered to
have no webhooks.

Why: the specification makes webhooks a first alternative to paths and
components, and the validator had no awareness of it (OpenAPITools#93), so valid
webhooks-only documents failed the structural check.

Fixes OpenAPITools#93

Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 8 files

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

What: the tests now build the webhooks maps with Collections.singletonMap
and Collections.emptyMap instead of Map.of, which the codebase cannot
use: the build targets Java 8 and Map.of is Java 9+. The reflective read
of the swagger model behind an empoa wrapper also handles a null return
of getSw() by considering the document free of webhooks, as the method
comment describes, instead of failing with a NullPointerException.

Why: addresses two review notes on PR OpenAPITools#816.

Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[OAS 3.1.0] at least one of paths, components or webhooks must be set

1 participant