# operation-tags-declared

Source: https://apigenie.pl/docs/linter/openapi/rules/operation-tags-declared

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.12.0. Fixed by `--fix`. In the rulesets: Recommended at warning, Strict at error, All at error.

This rule checks that every tag an operation uses is declared in the document's `tags`.

## Rule details

The top-level `tags` give each tag its description, its external docs and its place in the
order; an undeclared tag has none of these. A tag that an operation uses and the document doesn't
declare is often a typo of a declared tag.

The rule reports `Tag "<name>" is not declared in the document's tags` on each operation, once for
each entry of its `tags` that is not declared.

A document without top-level `tags` gets a report for each tag of each operation. Turn the rule
off for an API that does not declare its tags.

## Examples

**Good**. The tag is declared.

```yaml
tags:
  - name: pets
    description: Everything about your pets
paths:
  /pets:
    get:
      tags: [pets]
```

**Bad**. `store` is used but not declared.

```yaml
tags:
  - name: pets
paths:
  /pets:
    get:
      tags: [pets, store]
```

## Automatic fixes

`--fix` adds each undeclared tag to `tags` by name only, once, in the order the operations use
them, and creates `tags` when the document has none. `tag-description-defined` then reports each
added tag until it has a description. When `tags-sorted` is on, the added tags go after the
declared ones, so a second `--fix` sorts them.
