operation-tags-defined

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at error

This rule checks whether every operation of a Swagger 2.0 document has at least one tag.

Rule details

Tags group operations. Documentation tools use them to build sections, and code generators use them to split generated clients into classes or modules. Untagged operations usually end up in a catch-all group.

The operation-tags-defined rule reports Operation has no tags defined for every operation whose tags list is missing or empty.

The OpenAPI linter has a rule of the same name, operation-tags-defined, for OpenAPI 3.x documents.

Turn the rule off for small APIs where grouping operations brings no value.

Examples

Good. The operation is tagged.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
tags:
  - name: pets
    description: Operations on pets.
paths:
  /pets:
    get:
      tags: [pets]
      responses:
        '200':
          description: A list of pets.

Bad. The first operation has no tags, the second has an empty list.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets.
    post:
      tags: []
      responses:
        '201':
          description: The pet was added.

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:
        operation-tags-defined: off

Related rules

Further reading

Was this helpful?