Linter rulesSwagger 2.0tag-description-defined

tag-description-defined

Since 0.9.0

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).

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

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x and AsyncAPI documents are linted by the OpenAPI and AsyncAPI linters, which have their own tag-description-defined rules.

Related rules

Further reading