Repository navigation
Conversation
Fixes OpenAPITools#725 When the validateOperationTag rule is enabled, operations referencing tags that are not declared in the root 'tags' section now produce a validation error listing the undeclared tags. Declared tags without a description are encouraged via a warning-level finding, rendered with a *WARNING* prefix by the new GenericStyleWarning error type. The new checks extend the existing validateOperationTag rule instead of introducing a dedicated parameter, since they address the same concern (tag hygiene at operation level) and keep the configuration surface unchanged.
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
Root-tag description findings (GenericStyleWarning) were collected in the same list as errors, and every consumer treated any entry in that list as a failure: with the default validateOperationTag=true, any spec with an undescribed root tag failed the Maven, Gradle and CLI runs. The CLI, Maven plugin and Gradle plugin consumers now print GenericStyleWarning entries through their warning loggers and only fail the run when at least one error (a non-warning finding) is reported. Warnings keep their *WARNING* rendering from GenericStyleWarning::toString. Covered by consumer-level tests: undescribed root tag -> run/build succeeds with the *WARNING* finding printed (CLI OutputUtilsTest, Maven integration test, Gradle functional test); undeclared operation tag -> run/build still fails. Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>
getDeclaredTagNames() rebuilt the declared-tags set from the root tags section for every operation. The set is now built once in validateOperations() and passed to getUndeclaredTags(), so the per-operation check no longer reconstructs it. getDeclaredTagNames() itself is unchanged and both methods stay private, so there is no public API or behavior change. See the review discussion on PR OpenAPITools#810 (OpenAPITools#810 (comment)). 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.
Description
Implements #725 (approved by @JFCote: "this is a great suggestion!"): the validator now checks that the tags used by operations are declared in the root
tagssection, and encourages descriptions on the declared root tags.Rule semantics
Both checks are part of the existing
validateOperationTagrule — no new parameter is introduced (see "Design decision" below).When
validateOperationTagis enabled (default):Undeclared operation tags → error. If an operation references a tag that is not declared in the root
tagssection (including the case where the root section is missing entirely), the operation gets a validation error listing its undeclared tags:The existing "tags collection should be present" check is unchanged.
Root tag without description → warning. Each tag declared in the root
tagssection without a description produces a warning-level finding:Warnings are a new concept here, implemented in a fully additive way: a new
GenericStyleWarningsubclass ofStyleErrorrenders with a*WARNING*prefix instead of*ERROR*, and nothing existing is reclassified. The consumers (CLI, Gradle plugin, Maven plugin) print these findings through their warning loggers and exclude them from their failure decisions: the run/build fails only when at least one error (a non-warning finding) is reported, so an undescribed root tag never fails Maven/Gradle/CLI runs.Design decision: piggybacking on
validateOperationTagThe new checks extend the existing
validateOperationTagrule rather than introducing a dedicated parameter, because they address the same concern (tag hygiene at operation level) and this keeps the configuration surface unchanged for CLI, Gradle and Maven users. If the maintainers prefer an opt-in flag (e.g.validateOperationTagsDeclared), I'm happy to rework it — that would touchValidatorParametersplus the three plugin frontends.Test fixtures
The test specs used by the CLI (
some.yaml) and the lib tests (createValidOpenAPI()) now declare the tags they use, keeping their existing expectations intact under the new rule.Tests
OpenApiSpecStyleValidatorTest: operation using an undeclared tag → error (flag on/off parameterized); all undeclared tags of an operation are listed in one error; root tag without description →*WARNING*finding (flag on/off parameterized); all-declared spec → clean.ErrorAggregatorTest: coverage for the two new aggregator methods.GenericStyleWarningTest: equals/hashCode contract (EqualsVerifier), mirroringGenericStyleErrorTest.*WARNING*finding printed (OutputUtilsTest, Maven pluginIntegrationTest, Gradle plugin functional test); undeclared operation tag → run/build still fails (Maven pluginIntegrationTest, Gradle plugin functional test)../gradlew spotlessApply testbuild passes (JDK 17, Gradle 7.6.2), includingfunctionalTestfor the Gradle plugin.Fixes #725
Summary by cubic
Extends the
validateOperationTagrule to enforce that operation tags are declared in the roottagssection and encourage descriptions on declared tags, fixing #725.tagssection now fail with an error listing the undeclared tags.*WARNING*prefix by the newGenericStyleWarningtype. Warnings are printed but never fail the run; only errors do.Written for commit 6862000. Summary will update on new commits.