operation-description-defined

This rule checks each operation’s description in an OpenAPI schema and warns if the description is empty.

Rule Details

Meaningful descriptions make it easier to use an API correctly.

The operation-description-defined rule is designed to ensure that each operation in an OpenAPI schema has a description. This description is crucial as it provides information about what the operation does.

The rule checks all operations defined in an OpenAPI schema and raises an issue if operation’s description:

• is missing or empty
• 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:
    operation-description-defined:
      - warning
      - 20

Examples

Good. The following operation has a meaningful and useful description.

paths:
  /users:
    get:
      description: Retrieves a list of users
      responses:
        "200":
          description: |
            Returns a paged list of user resources, optionally filtered and sorted.

Bad. Operation does not have a description. It is not immediatelu clear, for example, whether this collection can be filtered.

paths:
  /users:
    get:
      description: Retrieves a list of users
      responses:
        "200": {}

Bad. The following operation have a meaningless description.

paths:
  /users:
    get:
      description: TBD
      responses:
        "200": {}

When Not to Use It

We recommend to always enable this rule.

Compatibility

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