# operation-description-defined

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

This rule checks each operation's description in an OpenAPI schema and warns
if the description is empty.

## Rule Details

Meaningful descriptions make it easier to use an API correctly.

The `operation-description-defined` rule is designed to ensure that each
operation in an OpenAPI schema has a description. This description is crucial
as it provides information about what the operation does.

The rule checks all operations defined in an OpenAPI schema and raises
an issue if operation'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:
    operation-description-defined:
      - warning
      - 20
```

## Examples

**Good**. The following operation has a meaningful and useful description.

```yaml
paths:
  /users:
    get:
      description: Retrieves a list of users
      responses:
        "200":
          description: |
            Returns a paged list of user resources, optionally filtered and sorted.
```

**Bad**. Operation does not have a description. It is not immediatelu clear,
for example, whether this collection can be filtered.

```yaml
paths:
  /users:
    get:
      description: Retrieves a list of users
      responses:
        "200": {}
```

**Bad**. The following operation have a meaningless description.

```yaml
paths:
  /users:
    get:
      description: TBD
      responses:
        "200": {}
```

## When Not to Use It

We recommend to always enable this rule.

## Compatibility

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