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
Was this helpful?