Validate that operation tags are declared in the root tags section

IN
7d ago
+516-7

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):

  1. Undeclared operation tags → error. If an operation references a tag that is not declared in the root tags section (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: someTag
    

    The existing "tags collection should be present" check is unchanged.

  2. Root tag without description → warning. Each tag declared in the root tags section without a description produces a warning-level finding:

    *WARNING* Section: OpenAPI: 'description' in tag 'demo' -> This field should be present and not empty
    

    Warnings are a new concept here, implemented in a fully additive way: a new GenericStyleWarning subclass of StyleError renders 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), mirroring GenericStyleErrorTest.
  • Consumers: undescribed root tag → run/build succeeds with the *WARNING* finding printed (OutputUtilsTest, Maven plugin IntegrationTest, Gradle plugin functional test); undeclared operation tag → run/build still fails (Maven plugin IntegrationTest, Gradle plugin functional test).
  • Full ./gradlew spotlessApply test build passes (JDK 17, Gradle 7.6.2), including functionalTest for 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 tags section 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 new GenericStyleWarning type. 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.