tags-unique
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks whether the tags in the root tags array of a Swagger 2.0
document have unique names, comparing names case-insensitively.
Rule details
The Swagger 2.0 specification requires tag names to be unique. Tags whose names differ only in letter case raise the same question: one group of operations, or two?
The tags-unique rule reports Tag name is not unique (<name>) for each
duplicate. Names are compared after converting ASCII letters to lower case.
The issue normally points at the later duplicate; when the earlier tag has
only a name and the later one has more properties, it points at the earlier
tag instead.
The unique-tag check of the swagger-validation rule reports exact
duplicates too, but it is disabled by default in favor of this rule.
The OpenAPI and AsyncAPI linters have rules of the same name, tags-unique and tags-unique.
Examples
Good.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths: {}
tags:
- name: pets
- name: users
Bad. Two tags differ only in letter case.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths: {}
tags:
- name: pets
description: Operations on the pets of the shelter.
- name: Pets
description: Is this another tag, or a typo?
Automatic fixes
When invoked with --fix, the rule removes a duplicate tag from the root
tags array when it is safe to do so:
- a duplicate that has only a
nameis removed, - when the earlier tag has only a
nameand the later duplicate has more properties, the earlier tag is removed, - a duplicate whose properties other than
nameare equal to those of the earlier tag is removed.
Duplicates with different descriptions, external documentation or extensions are reported, but left for manual resolution.
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:
tags-unique: off