Repository navigation
Conversation
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>
There was a problem hiding this comment.
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
OpenAPI 3.1.0 requires at least one of
paths,componentsorwebhooksto 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 thepaths/componentspair, but it had no awareness ofwebhooks, so a valid webhooks-only document was reported as an error:The check now also treats the document as non-empty when webhooks are declared, and the message names the three alternatives:
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
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 (Bump org.eclipse.microprofile.openapi:microprofile-openapi-api from 3.1.1 to 4.0.2 #798), the first lookup handles it directlypathsobject already counts as present since Fails when document doesn't contain paths #190), and an emptywebhooksobject counts as present too - what is reported is a document that declares none of the three at allTests
lib module (plain
@Test):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)webhooksmap counts as present, consistently withpathsErrorAggregatorTestcovers the renamed aggregator methodcli module (end-to-end):
./gradlew build -x :openapi-style-validator-gradle-plugin:functionalTestis 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, orwebhooks, and the error message names all three.Implementation notes
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.webhooksobject counts as present, consistent withpathsandcomponents.Written for commit 4a4eb73. Summary will update on new commits.