operation-id-unique
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error
This rule checks whether the operation IDs of a Swagger 2.0 document are unique.
Rule details
The Swagger 2.0 specification requires the operationId to be unique among
all operations of an API. Duplicate IDs break code generators, which name
methods after them, and make links to operations ambiguous.
The operation-id-unique rule reports Operation ID is not unique <id> for
every operation that repeats an ID already used by an earlier operation, in
document order. The first occurrence is not reported. Operations without an
operationId are ignored; the operation-id-defined rule reports them. Since
0.12.0, an empty or whitespace-only operationId is an error of reading the
document, reported before any rule runs; see
operation-id-defined.
The OpenAPI linter has a rule of the same name, operation-id-unique, for OpenAPI 3.x documents.
Turn the rule off only when no tooling relies on operation IDs; duplicate IDs violate the Swagger 2.0 specification.
Examples
Good. Each operation has its own ID.
swagger: '2.0'
info:
title: Users
version: 1.0.0
paths:
/users:
get:
operationId: getUsers
responses:
'200':
description: A list of users.
/users/{id}:
get:
operationId: getUserById
parameters:
- name: id
in: path
required: true
type: string
responses:
'200':
description: A single user.
Bad. Two operations share the same ID.
swagger: '2.0'
info:
title: Downloads
version: 1.0.0
paths:
/downloads/{id}:
parameters:
- name: id
in: path
required: true
type: string
patch:
operationId: cancelDownload
responses:
'200':
description: The download was updated.
delete:
operationId: cancelDownload
responses:
'204':
description: The download was cancelled.
Automatic fixes
--fix keeps the first occurrence of an ID and
replaces every later duplicate with an ID generated the same way as by the
operation-id-defined rule, from the HTTP method and the path (for example
getPetsById for GET /pets/{id}). IDs already used in the document are
reserved, and collisions get a numeric suffix starting at 2.
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-id-unique: off