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 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.

The OpenAPI linter has a rule of the same name, operation-description-defined, for OpenAPI 3.x documents.

Turn the rule off when operations are documented outside of the Swagger document.

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.

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.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        operation-description-defined: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?