operation-description-defined

Since 0.0.1 · In the rulesets: Recommended at error, Strict at error, All at error

This rule checks that every operation has a description of at least 10 characters.

Rule details

The description is where an operation says what it does beyond its method and path: what the list is filtered by, what a delete does to related resources, which errors to expect. Generated documentation and clients show it; without it, the reader guesses. A placeholder such as TBD is shorter than the minimum and reported too.

The rule reports Operation has no meaningful description.

Configuration

A positive integer: the minimal length of a description. 10 by default.

Configuration example. Descriptions of at least 20 characters.

commands:
  lint:
    rules:
      operation-description-defined:
        - warning
        - 20

Examples

Good. The description says what the list holds and what can be done with it.

paths:
  /users:
    get:
      description: Returns a paged list of users, filtered and sorted by the query parameters.
      responses:
        "200":
          description: A page of users.

Bad. No description.

paths:
  /users:
    get:
      responses:
        "200":
          description: A page of users.

Bad. A placeholder.

paths:
  /users:
    get:
      description: TBD
      responses:
        "200":
          description: A page of users.

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

commands:
  lint:
    rules:
      operation-description-defined: off
Was this helpful?