tag-description-defined

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at warning

This rule checks whether each tag declared in the root tags array of a Swagger 2.0 document has a meaningful description.

Rule details

Tag descriptions explain the purpose of the groups of operations, which makes the structure of the API easier to understand in documentation and API consoles.

The tag-description-defined rule reports Tag '<name>' has no meaningful description defined for every tag whose description:

  • is missing or empty,
  • is shorter than the configured minimal length (10 characters by default),
  • consists of whitespace only,
  • is one of the placeholders TODO, FIXME or TBD (in any letter case).

The OpenAPI and AsyncAPI linters have rules of the same name, tag-description-defined and tag-description-defined.

Configuration

A single positive integer: the minimal length of a meaningful description. The default value is 10.

Configuration example

version: "1.0"
commands:
  lint:
    swagger:
      rules:
        tag-description-defined: [warning, 20]

Examples

Good.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths: {}
tags:
  - name: pets
    description: Operations on the pets of the shelter.
  - name: users
    description: Operations on the accounts of the shelter staff.

Bad. The first tag has a placeholder description, the second has none.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths: {}
tags:
  - name: pets
    description: TBD
  - name: users

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.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        tag-description-defined: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?