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

Related rules

Last updated on View as Markdown
Was this helpful?