"Every operation must have unique operationId" (operation-operationId-unique)
Last checked and updated
Two operations in the document have the same operationId. The OpenAPI specification says the id "MUST be unique among all operations described in the API". The linter rule is Spectral's operation-operationId-unique, an error by default.
How it is reported
paths:
/orders:
get:
operationId: getOrders
/orders/{orderId}:
get:
operationId: getOrders
$ apigit lint dup.yaml
30:20 error operation-operationId-unique Every operation must have unique "operationId". (paths./orders/{orderId}.get.operationId)
The finding is on the second use: line 30 of the full file, the operation GET /orders/{orderId}. The first one (line 14) is not marked; search the file for the id to find it.
Why it matters beyond the linter
Tools may use the id as a name. A client generator that makes a method from each one has to do something with a duplicate: merge, rename or fail, depending on the generator. Some documentation tools build links from ids, and anything that selects an operation by id may reach only one of the pair.
How it happens
| Cause | Fix |
|---|---|
| An operation was copied and its id not changed | Rename the copy |
The list and the single-item operation got the same name (getOrders twice) | listOrders and getOrder |
The same id under two paths or two versions (/v1/orders, /v2/orders) | Include what differs: listOrdersV2 |
| Files merged from two teams | Prefix by area: billingListInvoices |
A scheme that does not collide
verb + resource, with the list and the item told apart by the verb and the number:
| Operation | operationId |
|---|---|
GET /orders | listOrders |
POST /orders | createOrder |
GET /orders/{orderId} | getOrder |
PATCH /orders/{orderId} | updateOrder |
DELETE /orders/{orderId} | deleteOrder |
GET /orders/{orderId}/items | listOrderItems |
More on choosing ids, and the characters to avoid: operationId in OpenAPI.