Linter rulesSwagger 2.0parameter-description-defined

parameter-description-defined

Since 0.9.0

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

Rule Details

A parameter’s name rarely tells everything about its meaning, accepted values and effect. A description fills that gap in generated documentation and clients.

The parameter-description-defined rule checks parameters of operations, of path items and the shared parameters under the root parameters, and reports Parameter '<name>' has no meaningful description when the description:

  • is missing or empty,
  • is shorter than the configured minimal length (10 characters by default),
  • consists of whitespace only,
  • is TODO, FIXME or TBD (case-insensitive).

Parameter references ($ref) are skipped; the referenced shared parameter is checked where it is defined.

Configuration

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

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

Examples

Good. Every parameter has a meaningful description.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      parameters:
        - $ref: '#/parameters/limit'
      responses:
        '200':
          description: A list of pets.
parameters:
  limit:
    name: limit
    in: query
    type: integer
    description: The maximum number of pets to return.

Bad. The path parameter has no description and the query parameter has a description that is too short.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets/{id}:
    parameters:
      - name: id
        in: path
        required: true
        type: string
    get:
      parameters:
        - name: fields
          in: query
          type: string
          description: Fields
      responses:
        '200':
          description: A single pet.

When Not to Use It

You may disable this rule when parameters are self-explanatory or 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.

Related rules

Further reading