FastAPI 0.112.0 Duplicate operation_id Warning: Should the framework enforce uniqueness?

Answer

FastAPI should treat duplicate operation_id values as a hard error at startup rather than silently allowing them.

Confirmed facts

• FastAPI derives operation_id from the endpoint function name and the path.
• When two routers produce the same identifier, the framework logs a warning but still writes both entries to the OpenAPI schema, yielding non‑unique operation_id values.
• OpenAPI‑based tools (Swagger UI, OpenAPI Generator, custom SDK generators) assume every operation_id is unique; duplicates cause method name collisions or UI showing only the last endpoint.
• Runtime request handling does not use operation_id, so neither strategy changes latency or error rates.

Likely explanation

The warning‑only approach leaves the schema in an invalid state for consumers that rely on uniqueness. Because the identifier is only documentation metadata, making the conflict a hard error does not affect request processing but forces developers to resolve the clash before the application starts, preventing silent schema corruption.

Steps to verify the current behavior

1. Create a minimal FastAPI app with two routers, each defining a GET endpoint with the same function name and path (e.g., def items(): under /items).
2. Run the app with Uvicorn and note the console warning about duplicate operation_id.
3. Request /openapi.json and confirm that the two paths share the same operation_id value.
4. Add explicit operation_id arguments to the route decorators to make them unique; the warning disappears and the schema shows distinct IDs.

Recommendation and migration impact

If your project distributes generated SDKs or relies on stable operation_id values for external consumers, consider an auto‑rename strategy (e.g., appending a suffix) and bump the SDK version, because a hard error would break existing clients.

If the OpenAPI schema is used only for internal documentation or tooling that can be regenerated, enable the hard error. This can be done by setting app = FastAPI(..., generate_unique_id_function=custom_func) that raises on duplicates, or by awaiting a future FastAPI release that treats the warning as an error.

Missing diagnostic detail

Do you publish or version SDKs generated from the OpenAPI spec for external consumers? Knowing this determines whether a hard error (preferred for internal use) or an auto‑rename with version bump (required for external SDKs) is the safer path.