# tag-description-defined

Source: https://apigenie.pl/docs/linter/swagger/rules/tag-description-defined

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**

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

## Examples

**Good**.

```yaml
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.

```yaml
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.