Description
An operationId identifies an API operation and must be unique across the API when provided. Reusing it for different endpoints or methods can prevent generators, SDKs and documentation tools from distinguishing those operations.
Potential impact
SDK method-name collisions or references to the wrong operation can cause generation and integration errors.
Remediation
Check defined operationId values for duplicates and use names that reflect each operation’s purpose. When renaming one, update links, generated clients and automation that refer to it.
Examples
These OpenAPI 3.0 excerpts compare operation identifiers only. They omit the document’s info and the responses required for each operation.
Before
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"operationId": "operation_id"
},
"post": {
"operationId": "operation_id"
}
}
}
}
After
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"operationId": "listRootResource"
},
"post": {
"operationId": "createRootResource"
}
}
}
}
The before example assigns the same identifier to GET and POST. The after example names the retrieval and creation operations separately. Renaming an identifier alone does not change the server’s paths or behavior.