tag-description-defined
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at warning
This rule checks whether every tag of an AsyncAPI document has a meaningful description.
Rule details
Documentation generators usually render tags as section headers, and their descriptions as the introduction of each section. A tag without a description leaves readers guessing what the grouped operations have in common.
The tag-description-defined rule checks every Tag object of the document,
wherever it is defined: in info.tags, in the tags of servers, channels, operations,
operation traits, messages and message traits, and in components/tags.
It reports Tag '<name>' has no meaningful description defined for every tag
whose description:
- is missing, empty or blank,
- is shorter than the configured minimal length,
- is a placeholder:
TODO,FIXMEorTBD(case-insensitive).
Turn the rule off if the tag names are self-explanatory.
Configuration
The configuration block is a positive integer: the minimal length of a
description, in characters. The default value is 10.
Configuration example.
version: "1.0"
commands:
lint:
asyncapi:
rules:
tag-description-defined: [warning, 20]
Examples
Good.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
tags:
- name: adoption
description: Events related to adopting and returning pets.
Bad.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
tags:
- name: adoption
- name: inventory
description: TBD
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.asyncapi has the details.
commands:
lint:
asyncapi:
rules:
tag-description-defined: off