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