operation-id-unique

Since 0.0.1 · fixed by --fix

This rule checks whether operations defined in an OpenAPI schema have unique IDs.

Rule Details

Duplicate operation ID make it difficult to reason about their purpose, as well as about.

The operation-id-unique rule checks IDs of operations defined in an OpenAPI schema and warn if duplicates found. Empty operation IDs do not count as duplicates.

Configuration

The optional nonPathNaming value controls generated webhook and component path-item names: scope-prefix (default), path-like, or scope-suffix.

Examples

Good. It is immediately visible what each operation does.

paths:
  /users:
    get:
      operationId: getUsers
      responses:
        "200":
          description: A list of users.
  /users/{id}:
    get:
      operationId: getUserById
      responses:
        "200":
          description: A single user.

Bad. Two operations have identical IDs, which makes it difficult to decide which one to use in each case.

paths:
    /downloads:
        patch:
            # changes the status to 'cancelled'
            operationId: cancelDownload
            ...
        delete:
            operationId: cancelDownload
            ...

When Not to Use It

We recommend to always enable this rule.

Automatic fixes

When invoked with --fix, this rule keeps the first occurrence and regenerates later duplicates using the same deterministic generator and collision policy as operation-id-defined.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.