Skip to content

Latest commit

 

History

History
98 lines (71 loc) · 2.33 KB

tag-description.md

File metadata and controls

98 lines (71 loc) · 2.33 KB
slug
/docs/cli/rules/oas/tag-description

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.

Related rules

Resources