Last updated

tag-description

Requires that the tags all have a non-empty description.

OASCompatibility
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
OptionTypeDescription
severitystringPossible 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.

Resources

 
Next page