operation-tags-defined

This rule checks each operations’ tags in an OpenAPI schema and warns if any of them are empty lists.

Rule Details

Tags help undertand the logical grouping of OpenAPI operations, which in turn helps in using the API correctly.

The operation-tags-defined rule is designed to ensure that each operation in an OpenAPI schema has at least one tag. Tags are used for logical grouping of operations, which aids in understanding and using the API.

A situation when OpenAPI schema itself does not define any tags is not treated as an issue.

Configuration

None.

Examples

Good. OpenAPI defines tags, which are used by an operation

paths:
  /users:
    get:
      tags:
        - Users
      responses:
        "200":
          description: A list of users.
tags:
  - name: Users

Good. OpenAPI does not define any tags.

paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.

Bad. Operation does not define any tags.

paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
tags:
  - name: Users

When Not to Use It

When you decide not to use tags in your API contracts. In this case, the list of tags in OpenAPI object should be empty.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.