Features
✨ Add support for shared/top-level parameters (dependencies, tags, etc). PR #2434 by @tiangolo.
Up to now, for several options, the only way to apply them to a group of path operations was in include_router. That works well, but the call to app.include_router() or router.include_router() is normally done in another file.
That means that, for example, to apply authentication to all the path operations in a router it would end up being done in a different file, instead of keeping related logic together.
Setting options in include_router still makes sense in some cases, for example, to override or increase configurations from a third party router included in an app. But in a router that is part of a bigger application, it would probably make more sense to add those settings when creating the APIRouter.
In FastAPI
This allows setting the (mostly new) parameters (additionally to the already existing parameters):
default_response_class: updated to handle defaults in APIRouter and include_router.
dependencies: to include
✨ top-level dependencies
✨ that apply to the whole application. E.g. to add global authentication.
callbacks: OpenAPI callbacks that apply to all the path operations.
deprecated: to mark all the path operations as deprecated.
🤷
include_in_schema: to allow excluding all the path operations from the OpenAPI schema.
responses: OpenAPI responses that apply to all the path operations.
For example:
from fastapi import FastAPI, Depends
async def some_dependency():
return
app = FastAPI(dependencies=[Depends(some_dependency)])
In APIRouter
This allows setting the (mostly new) parameters (additionally to the already existing parameters):
default_response_class: updated to handle defaults in APIRouter and include_router. For example, it's not needed to set it explicitly when creating callbacks.
dependencies: to include
✨ router-level dependencies
✨ that apply to all the path operations in a router. Up to now, this was only possible with include_router.
callbacks: OpenAPI callbacks that apply to all the path operations in this router.
deprecated: to mark all the path operations in a router as deprecated.
include_in_schema: to allow excluding all the path operations in a router from the OpenAPI schema.
responses: OpenAPI responses that apply to all the path operations in a router.
prefix: to set the path prefix for a router. Up to now, this was only possible when calling include_router.
tags: OpenAPI tags to apply to all the path operations in this router.
For example:
from fastapi import APIRouter, Depends
async def some_dependency():
return
router = APIRouter(prefix="/users", dependencies=[Depends(some_dependency)])
In include_router
Most of these settings are now supported in APIRouter, which normally lives closer to the related code, so it is recommended to use APIRouter when possible.
But include_router is still useful to, for example, adding options (like dependencies, prefix, and tags) when including a third party router, or a generic router that is shared between several projects.
This PR allows setting the (mostly new) parameters (additionally to the already existing parameters):
default_response_class: updated to handle defaults in APIRouter and FastAPI.
deprecated: to mark all the path operations in a router as deprecated in OpenAPI.
include_in_schema: to allow disabling all the path operations from showing in the OpenAPI schema.
callbacks: OpenAPI callbacks that apply to all the path operations in this router.
Note: all the previous parameters are still there, so it's still possible to declare dependencies in include_router.
Breaking Changes
PR #2434 includes several improvements that shouldn't affect normal use cases, but could affect in advanced scenarios:
If you are testing the generated OpenAPI (you shouldn't, FastAPI already tests it extensively for you): the order for tags in include_router and path operations was updated for consistency, but it's a simple order change.
If you have advanced custom logic to access each route's route.response_class, or the router.default_response_class, or the app.default_response_class: the default value for response_class in APIRoute and for default_response_class in APIRouter and FastAPI is now a DefaultPlaceholder used internally to handle and solve default values and overrides. The actual response class inside the DefaultPlaceholder is available at route.response_class.value.
Docs
Translations
🌐 Add Japanese translation for Advanced - Custom Response. PR #2193 by @Attsun1031.
🌐 Add Chinese translation for Benchmarks. PR #2119 by @spaceack.
🌐 Add Chinese translation for Tutorial - Body - Nested Models. PR #1609 by @waynerv.
🌐 Add Chinese translation for Advanced - Custom Response. PR #1459 by @RunningIkkyu.
🌐 Add Chinese translation for Advanced - Return a Response Directly. PR #1452 by @RunningIkkyu.
🌐 Add Chinese translation for Advanced - Additional Status Codes. PR #1451 by @RunningIkkyu.
🌐 Add Chinese translation for Advanced - Path Operation Advanced Configuration. PR #1447 by @RunningIkkyu.
🌐 Add Chinese translation for Advanced User Guide - Intro. PR #1445 by @RunningIkkyu.
Internal
🔧 Update TestDriven link to course in sponsors section. PR #2435 by @tiangolo.
🍱 Update sponsor logos. PR #2418 by @tiangolo.
💚 Fix disabling install of Material for MkDocs Insiders in forks, strike 1
⚾. PR #2340 by @tiangolo.
🐛 Fix disabling Material for MkDocs Insiders install in forks. PR #2339 by @tiangolo.
✨ Add silver sponsor WeTransfer. PR #2338 by @tiangolo.
✨ Set up and enable Material for MkDocs Insiders for the docs. PR #2325 by @tiangolo.