You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8e1d774
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/en/docs/advanced/openapi-callbacks.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -167,13 +167,13 @@ Notice how the callback URL used contains the URL received as a query parameter
167
167
168
168
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.
169
169
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:
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.
Copy file name to clipboardExpand all lines: docs/en/docs/advanced/path-operation-advanced-configuration.md
+3-9Lines changed: 3 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,17 +16,11 @@ You would have to make sure that it is unique for each operation.
16
16
17
17
### Using the *path operation function* name as the operationId { #using-the-path-operation-function-name-as-the-operationid }
18
18
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`.
20
20
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.
Copy file name to clipboardExpand all lines: docs/en/docs/how-to/extending-openapi.md
+9-1Lines changed: 9 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,7 +25,15 @@ And that function `get_openapi()` receives as parameters:
25
25
*`openapi_version`: The version of the OpenAPI specification used. By default, the latest: `3.1.0`.
26
26
*`summary`: A short summary of the API.
27
27
*`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.
Copy file name to clipboardExpand all lines: docs/en/docs/release-notes.md
+49Lines changed: 49 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,6 +7,55 @@ hide:
7
7
8
8
## Latest Changes
9
9
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)
Copy file name to clipboardExpand all lines: docs/en/docs/tutorial/bigger-applications.md
+17-5Lines changed: 17 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -396,17 +396,17 @@ It will include all the routes from that router as part of it.
396
396
397
397
/// note | Technical Details
398
398
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.
400
400
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.
402
402
403
403
///
404
404
405
405
/// tip
406
406
407
407
You don't have to worry about performance when including routers.
408
408
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.
410
410
411
411
So it won't affect performance. ⚡
412
412
@@ -461,7 +461,7 @@ The `APIRouter`s are not "mounted", they are not isolated from the rest of the a
461
461
462
462
This is because we want to include their *path operations* in the OpenAPI schema and the user interfaces.
463
463
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.
465
465
466
466
///
467
467
@@ -532,4 +532,16 @@ The same way you can include an `APIRouter` in a `FastAPI` application, you can
532
532
router.include_router(other_router)
533
533
```
534
534
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.
0 commit comments