operation-description

Checks that an Operation Object contains a description OR a summaryand that it meets a minimum number of words.

Descriptions and summaries for operations are really important. Documentation generation tools use this description as the main bulk of the documentation for the operation.

It’s amazing how often API authors leave this blank or don’t put anything meaningful in here.

The reason why both description and summary are checked? People tend to use them differently, sometimes omitting one, or the other, depending on how the specification is used.

Why did this violation appear?

An Operation Object or more are missing a description AND summary, or the if there is one, it’s got too few words to pass.

Bad example

paths:
  /vacuum/rules:
    post:
      responses:
        '200':
          ...

Good example

paths:
  /vacuum/rules:
    post:
      description: "This is an operation that returns interesting rules."
      responses:
        '200':
          ...

How do I fix this violation?

Add a description or a summary to the Operation, make it meaningful and useful.

Spectral Equivalent

The rule is equivalent to operation-description