parameter-description-defined

This rule checks every parameter defined in an OpenAPI schema and warns when a its description is empty or missing.

Rule Details

Meaningful descriptions make it easier to use an API correctly.

The parameter-description-defined rule is designed to ensure that each parameter in an OpenAPI schema has a meaningful description. These descriptions are crucial as they provide information about the purpose and usage of the parameter.

The rule checks all parameters defined in an OpenAPI schema and raises an issue if parameter’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:
    parameter-description-defined:
      - warning
      - 20

Examples

Good. Parameter description helps to understand its purpose and intended way of usage.

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          description: |
            The ID of the user to retrieve.
            Can also be `self`, which it interpreted as an ID of the
            currently logged in user.
          required: true
          schema:
            type: string

Bad. Without description it is not immediately obvious how this parameter is treated.

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

When Not to Use It

We recommend to always enable this rule.

Compatibility

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