parameter-description-defined

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at error

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

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.asyncapi has the details.

commands:
  lint:
    asyncapi:
      rules:
        parameter-description-defined: off

Related rules

Last updated on View as Markdown
Was this helpful?