Fix Duplicate OpenAPI operationId Errors
Every OpenAPI operationId must be unique across the complete document. Use stable names that remain distinct after files and services are combined.
Find duplicates in the resolved document
Lint the bundled or resolved API description used by documentation and code generation, not only individual source fragments. Two files can each appear valid while producing a duplicate after references, overlays, or service descriptions are merged. Record every path and HTTP method that shares the value. Remember that uniqueness applies across all operations, not only within one tag or path.
Understand why uniqueness matters
SDK generators commonly turn operation IDs into method names. A collision may fail generation, overwrite one method, add unstable suffixes, or create different public APIs across languages. Documentation systems, mock servers, gateways, and policy tools can also use operation IDs as keys. Fix the description instead of depending on a particular generator's collision behavior.
Choose a stable naming convention
Use a predictable verb-and-resource convention such as listUsers, getUser, createUser, and deleteUser. Include a parent resource or meaningful qualifier when two operations otherwise collide, for example listTeamUsers and listProjectUsers. Names should be readable, unique, and valid or easily transformed in target programming languages.
Avoid accidental instability
Do not generate operation IDs from array order or a temporary file name. Path-based generation can work, but define how parameters, versions, separators, and methods are normalized. Renaming an existing operation ID may rename generated SDK methods and break clients even when the HTTP endpoint is unchanged. Treat established operation IDs as part of the developer-facing contract and review changes deliberately.
Check merged services and versions
Federated descriptions often collide on generic names such as getStatus, search, or healthCheck. Add a service or bounded-context qualifier only where it improves uniqueness and meaning. If multiple API versions are published in one document, decide whether the version belongs in the operation ID; avoid it when versions are generated separately.
Prevent recurrence in CI
Run a linter on the final bundled specification for every pull request. Generate at least one representative SDK when operation IDs are a public code-generation contract. Review the diff for renamed methods, not just successful generation. Inspect the document locally with the OpenAPI Linter and compare revisions with the OpenAPI Diff tool.
Frequently Asked Questions
Must operationId be unique?
Yes, across every operation in the complete document.
Can duplicates break SDKs?
Yes. Methods may collide, be renamed, or disappear.
Should the HTTP method be included?
Only if it supports a stable, readable, cross-language convention.