operation-tags-declared

Since 0.12.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error

This rule checks that every tag an operation uses is declared in the document’s tags.

Rule details

The top-level tags give each tag its description, its external docs and its place in the order; an undeclared tag has none of these. A tag that an operation uses and the document doesn’t declare is often a typo of a declared tag.

The rule reports Tag "<name>" is not declared in the document's tags on each operation, once for each entry of its tags that is not declared.

A document without top-level tags gets a report for each tag of each operation. Turn the rule off for an API that does not declare its tags.

Examples

Good. The tag is declared.

tags:
  - name: pets
    description: Everything about your pets
paths:
  /pets:
    get:
      tags: [pets]

Bad. store is used but not declared.

tags:
  - name: pets
paths:
  /pets:
    get:
      tags: [pets, store]

Automatic fixes

--fix adds each undeclared tag to tags by name only, once, in the order the operations use them, and creates tags when the document has none. tag-description-defined then reports each added tag until it has a description. When tags-sorted is on, the added tags go after the declared ones, so a second --fix sorts them.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      operation-tags-declared: off

Related rules

Was this helpful?