Linter rulesSwagger 2.0operation-id-unique

operation-id-unique

Since 0.9.0 · fixed by --fix

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. Missing and empty IDs are ignored; the operation-id-defined rule reports them.

Configuration

None.

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

When invoked with --fix, this rule 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.

When Not to Use It

We recommend to always enable this rule, since duplicate operation IDs violate the Swagger 2.0 specification.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading