parameter-description-defined (AsyncAPI linter rule)

parameter-description-defined

Since 0.9.0

This rule checks whether every channel parameter of an AsyncAPI document has a meaningful description.

Rule Details

Channel parameters are the variable parts of channel addresses, such as userId in users.{userId}.signedUp. A description explains what the parameter identifies and which values it may take.

The parameter-description-defined rule checks the entries of the parameters map of every channel (in the root channels map and in components/channels), as well as the entries of components/parameters. References are checked where the referenced parameter is defined.

The rule reports Parameter '<name>' has no meaningful description for every parameter whose description:

is missing, empty or blank,
is shorter than the configured minimal length,
is a placeholder: TODO, FIXME or TBD (case-insensitive).

Configuration

The configuration block is a positive integer: the minimal length of a description, in characters. The default value is 10.

Configuration Example. The following configuration requires parameter descriptions to be at least 20 characters long.

version: "1.0"
commands:
  lint:
    asyncapi:
      rules:
        parameter-description-defined: [warning, 20]

Examples

Good.

asyncapi: 3.0.0
info:
  title: User Events
  version: 1.0.0
channels:
  userSignedUp:
    address: users.{userId}.signedUp
    parameters:
      userId:
        description: Identifier of the user who signed up.

Bad. The first parameter has no description at all, the second one has a placeholder.

asyncapi: 3.0.0
info:
  title: User Events
  version: 1.0.0
channels:
  userSignedUp:
    address: users.{region}.{userId}.signedUp
    parameters:
      region: {}
      userId:
        description: TODO

When Not to Use It

We recommend to always enable this rule.

Compatibility