Requires that the tags all have a non-empty description.
| OAS | Compatibility |
|---|---|
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
| 3.2 | ✅ |
tags:
- name: string
description: string
externalDocs: objecttags:
- name: Partner APIs
description: Endpoints used for integrations with partners and external collaborators.
- name: Customer APIs
description: Endpoints used for integrations with customers.
The default setting for this rule (in the built-in recommended configuration) is warn.
Verifies that each tag has a description because documentation! Did we say documentation? Documentation!
Remember folks, we use docs-as-code to write the docs, but the docs are the product, and your product should have a description.
To configure the rule, add it to the rules object in your configuration file. Set the desired severity for the rule.
rules:
tag-description: error| Option | Type | Description |
|---|---|---|
| severity | string | Possible values: off, warn, error. Default off (in recommended configuration). |
An example configuration:
rules:
tag-description: errorGiven this configuration:
rules:
tag-description: errorExample of incorrect tags:
tags:
- name: Partner APIs
- name: Customer APIsExample of correct tags:
tags:
- name: Partner APIs
description: Endpoints used for integrations with partners and external collaborators.
- name: Customer APIs
description: Endpoints used for integrations with customers.