Skip to content

Commit 8e1d774

Browse files
authored
♻️ Refactor internals to preserve APIRouter and APIRoute instances (#15745)
1 parent 016ab76 commit 8e1d774

11 files changed

Lines changed: 1877 additions & 316 deletions

File tree

‎docs/en/docs/advanced/openapi-callbacks.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -167,13 +167,13 @@ Notice how the callback URL used contains the URL received as a query parameter
167167

168168
At this point you have the *callback path operation(s)* needed (the one(s) that the *external developer* should implement in the *external API*) in the callback router you created above.
169169

170-
Now use the parameter `callbacks` in *your API's path operation decorator* to pass the attribute `.routes` (that's actually just a `list` of routes/*path operations*) from that callback router:
170+
Now use the parameter `callbacks` in *your API's path operation decorator* to pass the attribute `.routes` from that callback router:
171171

172172
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
173173

174174
/// tip
175175

176-
Notice that you are not passing the router itself (`invoices_callback_router`) to `callback=`, but the attribute `.routes`, as in `invoices_callback_router.routes`.
176+
Notice that you are not passing the router itself (`invoices_callback_router`) to `callbacks=`, but its `.routes`, as in `invoices_callback_router.routes`. FastAPI will use those routes to generate the callback OpenAPI documentation.
177177

178178
///
179179

‎docs/en/docs/advanced/path-operation-advanced-configuration.md‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,17 +16,11 @@ You would have to make sure that it is unique for each operation.
1616

1717
### Using the *path operation function* name as the operationId { #using-the-path-operation-function-name-as-the-operationid }
1818

19-
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`.
19+
If you want to use your APIs' function names as `operationId`s, you can pass a custom `generate_unique_id_function` to `FastAPI`.
2020

21-
You should do it after adding all your *path operations*.
21+
The function receives each `APIRoute` and returns the `operationId` to use for that path operation.
2222

23-
{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2, 12:21, 24] *}
24-
25-
/// tip
26-
27-
If you manually call `app.openapi()`, you should update the `operationId`s before that.
28-
29-
///
23+
{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2,5:6,9] *}
3024

3125
/// warning
3226

‎docs/en/docs/how-to/extending-openapi.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,15 @@ And that function `get_openapi()` receives as parameters:
2525
* `openapi_version`: The version of the OpenAPI specification used. By default, the latest: `3.1.0`.
2626
* `summary`: A short summary of the API.
2727
* `description`: The description of your API, this can include markdown and will be shown in the docs.
28-
* `routes`: A list of routes, these are each of the registered *path operations*. They are taken from `app.routes`.
28+
* `routes`: The routes from the application, taken from `app.routes`. FastAPI uses them to collect the registered *path operations*, including those from included routers.
29+
30+
/// tip | Technical Details
31+
32+
`app.routes` is a lower-level route tree. It can include route candidates that FastAPI uses internally for included routers, not only final `APIRoute` objects.
33+
34+
You can still pass `app.routes` to `get_openapi()`. FastAPI will traverse that route tree to collect the effective path operations.
35+
36+
///
2937

3038
/// note
3139

‎docs/en/docs/release-notes.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,55 @@ hide:
77

88
## Latest Changes
99

10+
♻️ Refactor internals to preserve `APIRouter` and `APIRoute` instances
11+
12+
Unblocks ✨ SO MANY THINGS ✨
13+
14+
Before this, `router.include_router(other_router)` would take each path operation from `other_router` and "clone" it, or recreate it from scratch.
15+
16+
This would mean that in the end there was only one top level router, part of the app.
17+
18+
The way it is structured here is that there are a few additional classes to handle intermediate metadata for router and route inclusion. That way the information of "router X includes Y and Y includes Z" is stored somewhere, without affecting (recreating / clonning) the final route.
19+
20+
#### Non Objectives
21+
22+
Dependencies for 404: previously I intended to support dependencies that would be executed even for 404, but that would conflict with the fact that a router could _not_ find a match, but the next router _did_ find a match. Executing dependencies in the router that did not find a match would not make sense, they could consume the request, body, etc. This original idea was discarded.
23+
24+
#### Breaking Changes
25+
26+
Now `router.routes` is no longer a plain list of `APIRoute` objects, it can contain these intermediate objects that can contain additional routers, forming a tree.
27+
28+
Any logic that depended on iterating on the `router.routes` directly would be affected, that logic cannot expect to be able to extract data from a plain list of routes, as it's no longer a plain list but a tree.
29+
30+
Additionally, any logic that iterated on `router.routes` to modify them would now also see these new objects, and would not see all the routes in the app.
31+
32+
`router.routes` should be considered an internal implementation detail, only passed around to the FastAPI functions that need it.
33+
34+
#### Features
35+
36+
* Adding routes (path operations) after a router is included now works, they are reflected as they are not copied.
37+
* Including `subrouter` in `mainrouter` can be done before adding routes (path operations) to `subrouter`, because now the the entire object is stored instead of copying the routes.
38+
* As routes are not copied, in some cases that might save some memory.
39+
40+
#### Alpha Features
41+
42+
This is not documented yet, so it's not officially supported yet and could change in the future.
43+
44+
But, as `APIRoute` and `APIRouter` instances are now preserved, they could be customized.
45+
46+
`APIRouter` has two new methods, `.matches()` and `.handle()`, counterpart to the existing ones in `APIRoute`. With this a router could customize how it matches and handles requests. For example, it could match only requests that include some specific header, for example for handling versions in headers.
47+
48+
Still, for now, consider this very experimental and potentially changing and breaking in the future.
49+
50+
#### Future Features Enabled
51+
52+
* Custom `APIRoute` subclasses (undocumented, but alraedy works as desccribed above)
53+
* Custom `APIRouter` subclasses (undocumented, but already works as described above)
54+
* Dependencies per router
55+
* Exception handlers per router
56+
* Middleware per router
57+
* Other features planned
58+
1059
### Docs
1160

1261
* 📝 Update FastAPI Cloud deployment instructions. PR [#15724](https://github.com/fastapi/fastapi/pull/15724) by [@alejsdev](https://github.com/alejsdev).

‎docs/en/docs/tutorial/bigger-applications.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -396,17 +396,17 @@ It will include all the routes from that router as part of it.
396396

397397
/// note | Technical Details
398398

399-
It will actually internally create a *path operation* for each *path operation* that was declared in the `APIRouter`.
399+
FastAPI keeps the original `APIRouter` and its `APIRoute`s active when the router is included in the main application.
400400

401-
So, behind the scenes, it will actually work as if everything was the same single app.
401+
That means custom `APIRouter` and `APIRoute` subclasses can still participate after the router is included.
402402

403403
///
404404

405405
/// tip
406406

407407
You don't have to worry about performance when including routers.
408408

409-
This will take microseconds and will only happen at startup.
409+
This is designed to be lightweight and to avoid adding overhead to each request.
410410

411411
So it won't affect performance. ⚡
412412

@@ -461,7 +461,7 @@ The `APIRouter`s are not "mounted", they are not isolated from the rest of the a
461461

462462
This is because we want to include their *path operations* in the OpenAPI schema and the user interfaces.
463463

464-
As we cannot just isolate them and "mount" them independently of the rest, the *path operations* are "cloned" (re-created), not included directly.
464+
FastAPI keeps the original routers and path operations active, and combines the router prefixes, dependencies, tags, responses, and other metadata when handling requests and generating OpenAPI.
465465

466466
///
467467

@@ -532,4 +532,16 @@ The same way you can include an `APIRouter` in a `FastAPI` application, you can
532532
router.include_router(other_router)
533533
```
534534

535-
Make sure you do it before including `router` in the `FastAPI` app, so that the *path operations* from `other_router` are also included.
535+
You can do this before or after including `router` in the `FastAPI` app. FastAPI will still include the *path operations* from `other_router` in routing and OpenAPI.
536+
537+
The same applies to *path operations* added later to the routers. They will be visible through the earlier inclusion too.
538+
539+
/// warning | Technical Details
540+
541+
Avoid directly mutating `router.routes` after including a router. FastAPI treats router inclusion as live, so the original router and its routes remain part of routing and OpenAPI generation.
542+
543+
Use documented APIs such as path operation decorators and `.include_router()` to add routes and routers.
544+
545+
Treat `router.routes` as a lower-level route tree that can contain route definitions and included routers, and avoid relying on it as a flat list of final path operations.
546+
547+
///
Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,14 @@
11
from fastapi import FastAPI
22
from fastapi.routing import APIRoute
33

4-
app = FastAPI()
54

6-
7-
@app.get("/items/")
8-
async def read_items():
9-
return [{"item_id": "Foo"}]
5+
def custom_generate_unique_id(route: APIRoute) -> str:
6+
return route.name
107

118

12-
def use_route_names_as_operation_ids(app: FastAPI) -> None:
13-
"""
14-
Simplify operation IDs so that generated API clients have simpler function
15-
names.
9+
app = FastAPI(generate_unique_id_function=custom_generate_unique_id)
1610

17-
Should be called only after all routes have been added.
18-
"""
19-
for route in app.routes:
20-
if isinstance(route, APIRoute):
21-
route.operation_id = route.name # in this case, 'read_items'
2211

23-
24-
use_route_names_as_operation_ids(app)
12+
@app.get("/items/")
13+
async def read_items():
14+
return [{"item_id": "Foo"}]

‎fastapi/applications.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -921,6 +921,7 @@ class Item(BaseModel):
921921
),
922922
] = "3.1.0"
923923
self.openapi_schema: dict[str, Any] | None = None
924+
self._openapi_routes_version: int | None = None
924925
if self.openapi_url:
925926
assert self.title, "A title must be provided for OpenAPI, e.g.: 'My API'"
926927
assert self.version, "A version must be provided for OpenAPI, e.g.: '2.1.0'"
@@ -1079,7 +1080,8 @@ def openapi(self) -> dict[str, Any]:
10791080
Read more in the
10801081
[FastAPI docs for OpenAPI](https://fastapi.tiangolo.com/how-to/extending-openapi/).
10811082
"""
1082-
if not self.openapi_schema:
1083+
routes_version = self.router._get_routes_version()
1084+
if not self.openapi_schema or self._openapi_routes_version != routes_version:
10831085
self.openapi_schema = get_openapi(
10841086
title=self.title,
10851087
version=self.version,
@@ -1096,6 +1098,7 @@ def openapi(self) -> dict[str, Any]:
10961098
separate_input_output_schemas=self.separate_input_output_schemas,
10971099
external_docs=self.openapi_external_docs,
10981100
)
1101+
self._openapi_routes_version = routes_version
10991102
return self.openapi_schema
11001103

11011104
def setup(self) -> None:

‎fastapi/openapi/utils.py‎

Lines changed: 44 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ def get_openapi_operation_request_body(
213213

214214

215215
def generate_operation_id(
216-
*, route: routing.APIRoute, method: str
216+
*, route: routing._APIRouteLike, method: str
217217
) -> str: # pragma: nocover
218218
warnings.warn(
219219
message="fastapi.openapi.utils.generate_operation_id() was deprecated, "
@@ -227,14 +227,14 @@ def generate_operation_id(
227227
return generate_operation_id_for_path(name=route.name, path=path, method=method)
228228

229229

230-
def generate_operation_summary(*, route: routing.APIRoute, method: str) -> str:
230+
def generate_operation_summary(*, route: routing._APIRouteLike, method: str) -> str:
231231
if route.summary:
232232
return route.summary
233233
return route.name.replace("_", " ").title()
234234

235235

236236
def get_openapi_operation_metadata(
237-
*, route: routing.APIRoute, method: str, operation_ids: set[str]
237+
*, route: routing._APIRouteLike, method: str, operation_ids: set[str]
238238
) -> dict[str, Any]:
239239
operation: dict[str, Any] = {}
240240
if route.tags:
@@ -259,7 +259,7 @@ def get_openapi_operation_metadata(
259259

260260
def get_openapi_path(
261261
*,
262-
route: routing.APIRoute,
262+
route: routing._APIRouteLike,
263263
operation_ids: set[str],
264264
model_name_map: ModelNameMap,
265265
field_mapping: dict[
@@ -329,7 +329,7 @@ def get_openapi_path(
329329
cb_security_schemes,
330330
cb_definitions,
331331
) = get_openapi_path(
332-
route=callback,
332+
route=cast(routing._APIRouteLike, callback),
333333
operation_ids=operation_ids,
334334
model_name_map=model_name_map,
335335
field_mapping=field_mapping,
@@ -478,31 +478,44 @@ def get_openapi_path(
478478
return path, security_schemes, definitions
479479

480480

481+
def _get_api_route_for_openapi(
482+
route: BaseRoute, route_context: routing._EffectiveRouteContext | None
483+
) -> routing._APIRouteLike | None:
484+
if route_context is not None and isinstance(
485+
route_context.original_route, routing.APIRoute
486+
):
487+
return cast(routing._APIRouteLike, route_context)
488+
if isinstance(route, routing.APIRoute):
489+
return cast(routing._APIRouteLike, route)
490+
return None
491+
492+
481493
def get_fields_from_routes(
482494
routes: Sequence[BaseRoute],
483495
) -> list[ModelField]:
484496
body_fields_from_routes: list[ModelField] = []
485497
responses_from_routes: list[ModelField] = []
486498
request_fields_from_routes: list[ModelField] = []
487499
callback_flat_models: list[ModelField] = []
488-
for route in routes:
489-
if not isinstance(route, routing.APIRoute):
500+
for route, route_context in routing._iter_routes_with_context(routes):
501+
api_route = _get_api_route_for_openapi(route, route_context)
502+
if api_route is None:
490503
continue
491-
if route.include_in_schema:
492-
if route.body_field:
493-
assert isinstance(route.body_field, ModelField), (
504+
if api_route.include_in_schema:
505+
if api_route.body_field:
506+
assert isinstance(api_route.body_field, ModelField), (
494507
"A request body must be a Pydantic Field"
495508
)
496-
body_fields_from_routes.append(route.body_field)
497-
if route.response_field:
498-
responses_from_routes.append(route.response_field)
499-
if route.response_fields:
500-
responses_from_routes.extend(route.response_fields.values())
501-
if route.stream_item_field:
502-
responses_from_routes.append(route.stream_item_field)
503-
if route.callbacks:
504-
callback_flat_models.extend(get_fields_from_routes(route.callbacks))
505-
params = get_flat_params(route.dependant)
509+
body_fields_from_routes.append(api_route.body_field)
510+
if api_route.response_field:
511+
responses_from_routes.append(api_route.response_field)
512+
if api_route.response_fields:
513+
responses_from_routes.extend(api_route.response_fields.values())
514+
if api_route.stream_item_field:
515+
responses_from_routes.append(api_route.stream_item_field)
516+
if api_route.callbacks:
517+
callback_flat_models.extend(get_fields_from_routes(api_route.callbacks))
518+
params = get_flat_params(api_route.dependant)
506519
request_fields_from_routes.extend(params)
507520

508521
flat_models = callback_flat_models + list(
@@ -546,18 +559,19 @@ def get_openapi(
546559
paths: dict[str, dict[str, Any]] = {}
547560
webhook_paths: dict[str, dict[str, Any]] = {}
548561
operation_ids: set[str] = set()
549-
all_fields = get_fields_from_routes(list(routes or []) + list(webhooks or []))
562+
all_fields = get_fields_from_routes(list(routes) + list(webhooks or []))
550563
flat_models = get_flat_models_from_fields(all_fields, known_models=set())
551564
model_name_map = get_model_name_map(flat_models)
552565
field_mapping, definitions = get_definitions(
553566
fields=all_fields,
554567
model_name_map=model_name_map,
555568
separate_input_output_schemas=separate_input_output_schemas,
556569
)
557-
for route in routes or []:
558-
if isinstance(route, routing.APIRoute):
570+
for route, route_context in routing._iter_routes_with_context(routes):
571+
api_route = _get_api_route_for_openapi(route, route_context)
572+
if api_route is not None:
559573
result = get_openapi_path(
560-
route=route,
574+
route=api_route,
561575
operation_ids=operation_ids,
562576
model_name_map=model_name_map,
563577
field_mapping=field_mapping,
@@ -566,17 +580,18 @@ def get_openapi(
566580
if result:
567581
path, security_schemes, path_definitions = result
568582
if path:
569-
paths.setdefault(route.path_format, {}).update(path)
583+
paths.setdefault(api_route.path_format, {}).update(path)
570584
if security_schemes:
571585
components.setdefault("securitySchemes", {}).update(
572586
security_schemes
573587
)
574588
if path_definitions:
575589
definitions.update(path_definitions)
576-
for webhook in webhooks or []:
577-
if isinstance(webhook, routing.APIRoute):
590+
for webhook, webhook_context in routing._iter_routes_with_context(webhooks or []):
591+
api_webhook = _get_api_route_for_openapi(webhook, webhook_context)
592+
if api_webhook is not None:
578593
result = get_openapi_path(
579-
route=webhook,
594+
route=api_webhook,
580595
operation_ids=operation_ids,
581596
model_name_map=model_name_map,
582597
field_mapping=field_mapping,
@@ -585,7 +600,7 @@ def get_openapi(
585600
if result:
586601
path, security_schemes, path_definitions = result
587602
if path:
588-
webhook_paths.setdefault(webhook.path_format, {}).update(path)
603+
webhook_paths.setdefault(api_webhook.path_format, {}).update(path)
589604
if security_schemes:
590605
components.setdefault("securitySchemes", {}).update(
591606
security_schemes

0 commit comments

Comments
 (0)