tag-description-defined

This rule checks whether each tag defined in an OpenAPI schema has a meaningful description.

Rule Details

Tag descriptions provide necessary context about the purpose and usage of the tag, improving the readability and understanding of the API’s structure.

The tag-description-defined rule checks all tags defined in an OpenAPI schema and raises an issue if any of them have description missing or empty.

Besides missing and empty descriptions this rule disregards descriptions that:

• consist of whitespace characters only
• consist of “empty” words like “TBD”, “TODO” and so on
• are shorter than the value specified in the configuration

Configuration

The configuration block is a single positive integer, which specifies the minimal number of characters in a “meaningful” description. The default value is 10.

Configuration Example

lint:
  rules:
    tag-description-defined:
      - warning
      - 20

Examples

Good.

tags:
    - name: User
        description: Operations related to the User entity.
    - name: Product
        description: Operations related to the Product entity.

Bad.

tags:
    - name: User
        description: ''
    - name: Product

When Not to Use It

We recommend to always enable this rule.

Compatibility

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