#2198·swag

v2: no guard against duplicate operationId when one handler is documented on multiple @Router lines

Author: ahridinCreated Jul 14, 2026Updated Jul 14, 2026

swag version: v2.0.0-rc5

When one shared Go handler function is documented with more than one @Router annotation (e.g. the same handler serves both a current and a legacy/versioned route), swag derives operationId from the function name for both, producing two operations with an identical operationId. OpenAPI requires operationId to be unique across the whole document, so this is a spec violation, and some codegen tools silently overwrite one operation's generated client method with the other's.

Expected/ask: would it be reasonable for swag to detect this and either (a) emit a warning, or (b) auto-suffix subsequent duplicates (e.g. by path or route order)? Happy to hear if there's already a recommended annotation to disambiguate this that I've missed.