operation-description-defined
Since 0.9.0 · In the rulesets: Recommended at error, Strict at error, All at error
This rule checks whether every operation of an AsyncAPI document has a meaningful description.
Rule details
An operation describes what the application does with a channel: whether it sends or receives messages, and why. A good description explains when the messages are produced or consumed, and what the application does with them.
The operation-description-defined rule reports
Operation has no meaningful description for every operation (in the root
operations map and in components/operations) whose description is
missing or shorter than the configured minimal length. Descriptions coming
from operation traits are not taken into account.
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 operation descriptions to be at least 30 characters long.
version: "1.0"
commands:
lint:
asyncapi:
rules:
operation-description-defined: [error, 30]
Examples
Good.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
channels:
petAdopted:
address: pets.adopted
operations:
onPetAdopted:
action: receive
channel:
$ref: "#/channels/petAdopted"
description: Updates the shelter inventory when a pet is adopted.
Bad. The operation has no description.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
channels:
petAdopted:
address: pets.adopted
operations:
onPetAdopted:
action: receive
channel:
$ref: "#/channels/petAdopted"
Bad. The description is too short to be useful.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
channels:
petAdopted:
address: pets.adopted
operations:
onPetAdopted:
action: receive
channel:
$ref: "#/channels/petAdopted"
description: Adopted
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:
operation-description-defined: off