spectral:oas error on by default

operation-operationId-unique

Every operation must have unique "operationId".

Applies to
paths
Selects
$.paths
Function
oasOpIdUnique
Specs
OpenAPI 2.0OpenAPI 3.0OpenAPI 3.1OpenAPI 3.2

Use it

This rule ships with OpenLint in spectral:oas. Extending the ruleset turns it on:

extends: spectral:oas
rules:
  operation-operationId-unique: error   # or off, or another severity

Definition

As defined in @openlint/openlint-rulesets. Functions show by name.

operation-operationId-unique:
  description: Every operation must have unique "operationId".
  severity: 0
  recommended: true
  given: $.paths
  then:
    function: oasOpIdUnique

About this rule

Every operation must have a unique operationId.

Why? A lot of documentation systems use this as an identifier, some SDK generators convert them to a method name, among other things.

Bad Example

paths:
  /pet:
    patch:
      operationId: "update-pet"
      responses:
        200:
          description: ok
    put:
      operationId: "update-pet"
      responses:
        200:
          description: ok

Good Example

paths:
  /pet:
    patch:
      operationId: "update-pet"
      responses:
        200:
          description: ok
    put:
      operationId: "replace-pet"
      responses:
        200:
          description: ok

Sources