tag-description

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

OAS Compatibility
2.0
3.0
3.1
Object structureExample
Copy
Copied
tags:
  - name: string
    description: string
    externalDocs: object
Copy
Copied
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 lint.rules section of your configuration file. Set the desired severity for the rule.

Copy
Copied
styleguide:
  rules:
    info-contact: error

Configuration

Option Type Description
severity string Possible values: off, warn, error. Default off (in recommended configuration).

An example configuration:

Copy
Copied
styleguide:
  rules:
    : error

Examples

Given this configuration:

Copy
Copied
styleguide:
  rules:
    : error

Example of incorrect tags:

Copy
Copied
tags:
  - name: Partner APIs
  - name: Customer APIs

Example of correct tags:

Copy
Copied
tags:
  - name: Partner APIs
    description: Endpoints used for integrations with partners and external collaborators.
  - name: Customer APIs
    description: Endpoints used for integrations with customers.

Related rules

Resources