# parameter-description-defined

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

This rule checks every parameter defined in an OpenAPI schema and warns when
a its description is empty or missing.

## Rule Details

Meaningful descriptions make it easier to use an API correctly.

The `parameter-description-defined` rule is designed to ensure that each
parameter in an OpenAPI schema has a meaningful description. These
descriptions are crucial as they provide information about the purpose and
usage of the parameter.

The rule checks all parameters defined in an OpenAPI schema and raises
an issue if parameter's description:

- is missing or empty
- consist of whitespace characters only
- consist of "empty" words like "TBD", "TODO" and so on
- are shorter than the value specified in the configuration

## Configuration

The configuration block is a single positive integer, which specifies the
minimal number of characters in a "meaningful" description. The default value
is 10.

**Configuration Example**

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

## Examples

**Good**. Parameter description helps to understand its purpose and intended
way of usage.

```yaml
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          description: |
            The ID of the user to retrieve.
            Can also be `self`, which it interpreted as an ID of the
            currently logged in user.
          required: true
          schema:
            type: string
```

**Bad**. Without description it is not immediately obvious how this parameter
is treated.

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

## When Not to Use It

We recommend to always enable this rule.

## Compatibility

This rule is compatible with all OpenAPI 3.x versions.