tag-description-defined
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at warning
This rule checks whether each tag declared in the root tags array of a
Swagger 2.0 document has a meaningful description.
Rule details
Tag descriptions explain the purpose of the groups of operations, which makes the structure of the API easier to understand in documentation and API consoles.
The tag-description-defined rule reports
Tag '<name>' has no meaningful description defined for every tag whose
description:
- is missing or empty,
- is shorter than the configured minimal length (10 characters by default),
- consists of whitespace only,
- is one of the placeholders
TODO,FIXMEorTBD(in any letter case).
The OpenAPI and AsyncAPI linters have rules of the same name, tag-description-defined and tag-description-defined.
Configuration
A single positive integer: the minimal length of a meaningful description. The default value is 10.
Configuration example
version: "1.0"
commands:
lint:
swagger:
rules:
tag-description-defined: [warning, 20]
Examples
Good.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths: {}
tags:
- name: pets
description: Operations on the pets of the shelter.
- name: users
description: Operations on the accounts of the shelter staff.
Bad. The first tag has a placeholder description, the second has none.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths: {}
tags:
- name: pets
description: TBD
- name: users
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.
commands:
lint:
swagger:
rules:
tag-description-defined: off