# operation-description-defined

Source: https://apigenie.pl/docs/linter/openapi/rules/operation-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 error, Strict at error, All at error.

This rule checks that every operation has a `description` of at least 10 characters.

## Rule details

The description is where an operation says what it does beyond its method and path: what the
list is filtered by, what a delete does to related resources, which errors to expect. Generated
documentation and clients show it; without it, the reader guesses. A placeholder such as `TBD`
is shorter than the minimum and reported too.

The rule reports `Operation has no meaningful description`.

## 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:
      operation-description-defined:
        - warning
        - 20
```

## Examples

**Good**. The description says what the list holds and what can be done with it.

```yaml
paths:
  /users:
    get:
      description: Returns a paged list of users, filtered and sorted by the query parameters.
      responses:
        "200":
          description: A page of users.
```

**Bad**. No description.

```yaml
paths:
  /users:
    get:
      responses:
        "200":
          description: A page of users.
```

**Bad**. A placeholder.

```yaml
paths:
  /users:
    get:
      description: TBD
      responses:
        "200":
          description: A page of users.
```
