operation-id-unique
Since 0.0.1 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error
This rule checks that no two operations share an operationId, callback operations included: the
specification requires the ID to be unique among all operations of the API. Empty IDs are left to
operation-id-defined.
Rule details
Generated clients, servers, documentation and mocks address an operation by its ID; two operations with the same one collide in all of them, and a reader of the document cannot tell which of the two a reference means.
The rule reports Operation ID is not unique ... on each repeat. An operation that several paths,
webhooks, callbacks or components share through a $ref is one operation, not a repeat.
Configuration
An object with one optional property, nonPathNaming, which decides how --fix names the
operations of webhooks, of callbacks and of the path items under components: scope-prefix (the
default), path-like or scope-suffix, as in
operation-id-defined.
Examples
Good. Each operation has a name of its own.
paths:
/users:
get:
operationId: listUsers
responses:
"200":
description: A page of users.
/users/{id}:
get:
operationId: getUser
responses:
"200":
description: One user.
Bad. Two operations called cancelDownload.
paths:
/downloads/{id}:
patch:
operationId: cancelDownload
responses:
"200":
description: The download, now cancelled.
delete:
operationId: cancelDownload
responses:
"204":
description: The download is removed.
Automatic fixes
--fix keeps the first operation with the ID and gives the later ones an ID generated from their
method and path, the way operation-id-defined does.
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.rules has the details.
commands:
lint:
rules:
operation-id-unique: off