operation-description-defined (AsyncAPI linter rule)

operation-description-defined

Since 0.9.0

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

When Not to Use It

We recommend to always enable this rule.

Compatibility