Validate that operation tags are declared in the root tags section
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 tags section, and encourages descriptions on the declared root tags.
Rule semantics
Both checks are part of the existing validateOperationTag rule — no new parameter is introduced (see "Design decision" below).
When validateOperationTag is 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:*ERROR* in Operation GET /ping 'tags' -> The following tags are used but not declared in the root 'tags' section: someTagThe 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:*WARNING* Section: OpenAPI: 'description' in tag 'demo' -> This field should be present and not emptyWarnings 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 validateOperationTag
The new checks extend the existing validateOperationTag rule 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 touch ValidatorParameters plus 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.- Consumers: undescribed root tag → run/build succeeds with the
*WARNING*finding printed (OutputUtilsTest, Maven pluginIntegrationTest, Gradle plugin functional test); undeclared operation tag → run/build still fails (Maven pluginIntegrationTest, Gradle plugin functional test). - Full
./gradlew spotlessApply testbuild passes (JDK 17, Gradle 7.6.2), includingfunctionalTestfor the Gradle plugin.
Fixes #725
Summary by cubic
Extends the validateOperationTag rule to enforce that operation tags are declared in the root tags section and encourage descriptions on declared tags, fixing #725.
- Operations referencing tags missing from the root
tagssection now fail with an error listing the undeclared tags. - Root tags without a description produce a new warning-level finding, rendered with a
*WARNING*prefix by the newGenericStyleWarningtype. Warnings are printed but never fail the run; only errors do. - No configuration parameter is added; CLI, Gradle, and Maven plugins pick up both checks unchanged.