tag-description
Requires that the tags all have a non-empty description.
| OAS | Compatibility |
|---|---|
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
tags: - name: string description: string externalDocs: object
tags: - 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.
API design principles
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.
Configuration
To configure the rule, add it to the rules object in your configuration file. Set the desired severity for the rule.
rules: info-contact: error
| Option | Type | Description |
|---|---|---|
| severity | string | Possible values: off, warn, error. Default off (in recommended configuration). |
An example configuration:
rules: tag-description: error
Examples
Given this configuration:
rules: tag-description: error
Example of incorrect tags:
tags: - name: Partner APIs - name: Customer APIs
Example 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.