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,FIXMEorTBD(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