operation-description-defined (Swagger 2.0 linter rule)

operation-description-defined

Since 0.9.0

This rule checks whether every operation of a Swagger 2.0 document has a meaningful description.

Rule Details

A description tells consumers what an operation does, when to call it and what side effects it has. Generated documentation and clients show it next to the operation.

The operation-description-defined rule reports Operation has no meaningful description for every operation whose description is missing or shorter than the configured minimal length (10 characters by default). The summary property does not count as a description.

Configuration

A single positive integer: the minimal number of characters of a description. The default is 10.

commands:
  lint:
    swagger:
      rules:
        operation-description-defined: [warning, 20]

Examples

Good. The operation has a meaningful description.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      description: Lists every pet of the store, ordered by name.
      responses:
        '200':
          description: A list of pets.

Bad. The first operation has no description, the second one has a description that is too short.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List pets
      responses:
        '200':
          description: A list of pets.
    post:
      description: Adds
      responses:
        '201':
          description: The pet was added.

When Not to Use It

You may disable this rule when operations are documented outside of the Swagger document.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.