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

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?