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, FIXME or TBD (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

Related rules

Last updated on View as Markdown
Was this helpful?