# parameter-description-defined

Source: https://apigenie.pl/docs/linter/swagger/rules/parameter-description-defined

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.

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

## Examples

**Good**. Every parameter has a meaningful description.

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

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