From e439ab81c703ee267c2abaf06ce21946f08e0cd5 Mon Sep 17 00:00:00 2001 From: wwenrr Date: Wed, 1 Apr 2026 10:31:30 +0000 Subject: [PATCH] docs: clarify operation_id conflicts for multi-method api_route --- .../path-operation-advanced-configuration.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/en/docs/advanced/path-operation-advanced-configuration.md b/docs/en/docs/advanced/path-operation-advanced-configuration.md index 800bf305dc..ffaf246fa7 100644 --- a/docs/en/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/en/docs/advanced/path-operation-advanced-configuration.md @@ -14,6 +14,18 @@ You would have to make sure that it is unique for each operation. {* ../../docs_src/path_operation_advanced_configuration/tutorial001_py310.py hl[6] *} +/// note + +If you register the same endpoint function for multiple HTTP methods with +`api_route()` / `add_api_route(..., methods=[...])`, OpenAPI operation IDs can +conflict unless you set explicit unique `operation_id` values. + +If you need unique operation IDs in generated OpenAPI clients, prefer separate +path operation decorators (for example `@app.get()` and `@app.post()`) or set +an explicit `operation_id` per operation. + +/// + ### Using the *path operation function* name as the operationId { #using-the-path-operation-function-name-as-the-operationid } If you want to use your APIs' function names as `operationId`s, you can iterate over all of them and override each *path operation's* `operation_id` using their `APIRoute.name`.