# tag-description-defined

Source: https://api-genie.dev/docs/linter/swagger/rules/tag-description-defined

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. 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](/docs/linter/openapi/rules/tag-description-defined) and
[tag-description-defined](/docs/linter/asyncapi/rules/tag-description-defined).

## 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
```
