operation-description

Requires every operation to contain a nonblank string description.

Attribute	Value
Category	Operations
Maturity	Gold
OpenAPI	Swagger 2.0; OpenAPI 3.0, 3.1, 3.2
Starter	Off
Lenient–Strict	Warning
Complete	Error

Intent

A description should explain behavior, constraints, or side effects that a short summary cannot convey.

Flags

An operation whose description is missing, non-string, empty, or whitespace-only.

Does not flag

An operation with any nonblank string description. Content quality is not evaluated.

See it fail

get:
  summary: Get a payment
  responses:
    '200': {description: OK}

Diagnostic: Operation object should contain `description` field.

Fix it

get:
  summary: Get a payment
  description: Returns the payment identified by the path parameter.
  responses:
    '200': {description: OK}

Configure

profiles:
  default:
    rules:
      extends: [recommended]
      override:
        operation-description: error

Nearby: operation-summary, operation-operationId.