# parameter-description-defined

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

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.0.1. In the rulesets: Recommended at warning, Strict at warning, All at error.

This rule checks that every parameter has a description of at least 10 characters that is not a
placeholder.

## Rule details

The name and the type of a parameter say what it holds; the description says what it does: which
values are special, whether a filter is exact or prefix, how two parameters interact. Generated
documentation shows it next to the parameter, and a client author reads it instead of trying.

The rule reports `Parameter '...' has no meaningful description` when the description is missing,
shorter than the minimum, white space only, or one of `TBD`, `TODO` and `FIXME`.

## Configuration

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

**Configuration example**. Descriptions of at least 20 characters.

```yaml
commands:
  lint:
    rules:
      parameter-description-defined:
        - warning
        - 20
```

## Examples

**Good**. The description says what the name does not.

```yaml
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          description: |
            The ID of the user, or `self` for the user the request is authenticated as.
          required: true
          schema:
            type: string
```

**Bad**. Nothing says that `self` is accepted.

```yaml
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
```
