operation-summary

Gives every API operation a short, human-readable summary.

Attribute	Value
Category	Operations
Maturity	Silver
OpenAPI	Swagger 2.0; OpenAPI 3.0, 3.1, 3.2
Starter	Warning
Lenient	Warning
Recommended	Error
Strict	Error
Complete	Error

Intent

Operation summaries appear in generated documentation, catalogs, and client tooling. A concise summary lets readers identify an endpoint without reading its full description.

Flags

This rule reports an operation when its summary is:

• missing;
• empty; or
• whitespace only.

Does not flag

• A non-empty summary.
• Missing or empty operation descriptions; operation-description handles those.
• Path-item summary fields that are not operation summaries.

This rule checks presence, not writing style or length.

See it fail

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      responses:
        "200":
          description: Orders returned.

Specmatic reports:

Operation object should contain `summary` field.

Fix it

Add one sentence fragment describing the operation:

paths:
  /orders:
    get:
      summary: List orders
      responses:
        "200":
          description: Orders returned.

Configure

specmatic-linter.yaml

profiles:
  default:
    rules:
      extends:
        - recommended
      override:
        operation-summary: warn

Use error to require summaries in CI, warn during adoption, or off to disable the rule.

Nearby rules

• operation-description
• operation-operationId
• operation-tag-defined