FastAPI

Main FastAPI application class for building high-performance APIs

The FastAPI class is the main entry point for creating FastAPI applications. It provides the core functionality for defining routes, handling requests, and generating OpenAPI documentation.

Class Signature

from fastapi import FastAPI

app = FastAPI(
    debug=False,
    title="FastAPI",
    summary=None,
    description="",
    version="0.1.0",
    openapi_url="/openapi.json",
    docs_url="/docs",
    redoc_url="/redoc",
)

Constructor Parameters

debug · bool · default: "False"

Boolean indicating if debug tracebacks should be returned on server errors.

title · str · default: "FastAPI"

The title of the API. It will be added to the generated OpenAPI (visible at /docs).

app = FastAPI(title="ChimichangApp")

summary · str | None · default: "None"

A short summary of the API. It will be added to the generated OpenAPI.

app = FastAPI(summary="Deadpond's favorite app. Nuff said.")

description · str · default: ""

A description of the API. Supports Markdown (using CommonMark syntax). It will be added to the generated OpenAPI.

app = FastAPI(
    description="""
    ChimichangApp API helps you do awesome stuff. 🚀
    
    ## Items
    You can **read items**.
    """
)

version · str · default: "0.1.0"

The version of the API. This is the version of your application, not the version of the OpenAPI specification.

app = FastAPI(version="1.0.0")

openapi_url · str | None · default: "/openapi.json"

The URL where the OpenAPI schema will be served from. Set to None to disable OpenAPI schema and automatic /docs and /redoc endpoints.

app = FastAPI(openapi_url="/api/v1/openapi.json")

openapi_tags · list[dict[str, Any]] | None · default: "None"

A list of tags used by OpenAPI. The order specifies the order shown in tools like Swagger UI.

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users.",
    },
    {
        "name": "items",
        "description": "Manage items.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://example.com/",
        },
    },
]
app = FastAPI(openapi_tags=tags_metadata)

servers · list[dict[str, str | Any]] | None · default: "None"

A list of dicts with connectivity information to target servers.

app = FastAPI(
    servers=[
        {"url": "https://stag.example.com", "description": "Staging environment"},
        {"url": "https://prod.example.com", "description": "Production environment"},
    ]
)

dependencies · Sequence[Depends] | None · default: "None"

A list of global dependencies, applied to each path operation including in sub-routers.

from fastapi import Depends, FastAPI
from .dependencies import func_dep_1, func_dep_2

app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)])

default_response_class · type[Response] · default: "JSONResponse"

The default response class to be used for all path operations.

from fastapi import FastAPI
from fastapi.responses import ORJSONResponse

app = FastAPI(default_response_class=ORJSONResponse)

redirect_slashes · bool · default: "True"

Whether to detect and redirect slashes in URLs when the client doesn’t use the same format.

app = FastAPI(redirect_slashes=True)

docs_url · str | None · default: "/docs"

The path to the automatic interactive API documentation (Swagger UI). Set to None to disable.

app = FastAPI(docs_url="/documentation")

redoc_url · str | None · default: "/redoc"

The path to the alternative automatic interactive API documentation (ReDoc). Set to None to disable.

app = FastAPI(redoc_url="/redocumentation")

swagger_ui_oauth2_redirect_url · str | None · default: "/docs/oauth2-redirect"

The OAuth2 redirect endpoint for the Swagger UI.

swagger_ui_init_oauth · dict[str, Any] | None · default: "None"

OAuth2 configuration for the Swagger UI.

middleware · Sequence[Middleware] | None · default: "None"

List of middleware to be added when creating the application.

exception_handlers · dict[int | type[Exception], Callable] | None · default: "None"

A dictionary with handlers for exceptions.

lifespan · Lifespan[AppType] | None · default: "None"

A Lifespan context manager handler for startup and shutdown events.

from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    print("Starting up")
    yield
    # Shutdown
    print("Shutting down")

app = FastAPI(lifespan=lifespan)

terms_of_service · str | None · default: "None"

A URL to the Terms of Service for your API.

app = FastAPI(terms_of_service="http://example.com/terms/")

contact · dict[str, str | Any] | None · default: "None"

A dictionary with the contact information for the exposed API.

app = FastAPI(
    contact={
        "name": "API Support",
        "url": "http://example.com/contact/",
        "email": "[e-mail]",
    }
)

license_info · dict[str, str | Any] | None · default: "None"

A dictionary with the license information for the exposed API.

app = FastAPI(
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    }
)

root_path · str · default: ""

A path prefix handled by a proxy that is not seen by the application but is seen by external clients.

app = FastAPI(root_path="/api/v1")

root_path_in_servers · bool · default: "True"

Whether to automatically generate the URLs in the servers field using the root_path.

responses · dict[int | str, dict[str, Any]] | None · default: "None"

Additional responses to be shown in OpenAPI.

callbacks · list[BaseRoute] | None · default: "None"

OpenAPI callbacks that should apply to all path operations.

webhooks · APIRouter | None · default: "None"

OpenAPI webhooks for the application.

deprecated · bool | None · default: "None"

Mark all path operations as deprecated.

include_in_schema · bool · default: "True"

Whether to include all path operations in the generated OpenAPI.

swagger_ui_parameters · dict[str, Any] | None · default: "None"

Parameters to configure Swagger UI.

generate_unique_id_function · Callable[[APIRoute], str] · default: "generate_unique_id"

Customize the function used to generate unique IDs for path operations.

separate_input_output_schemas · bool · default: "True"

Whether to generate separate OpenAPI schemas for request body and response body.

openapi_external_docs · dict[str, Any] | None · default: "None"

Additional external documentation links.

app = FastAPI(
    openapi_external_docs={
        "description": "Detailed API Reference",
        "url": "https://example.com/api-docs",
    }
)

strict_content_type · bool · default: "True"

Enable strict checking for request Content-Type headers. When True, requests with a body that do not include a Content-Type header will not be parsed as JSON.

Methods

Path Operation Decorators

@app.get(path, **kwargs)

Define a GET endpoint.

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

@app.post(path, **kwargs)

Define a POST endpoint.

@app.post("/items/")
async def create_item(item: Item):
    return item

@app.put(path, **kwargs)

Define a PUT endpoint.

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

@app.patch(path, **kwargs)

Define a PATCH endpoint.

@app.patch("/items/{item_id}")
async def partial_update_item(item_id: int, item: ItemUpdate):
    return {"item_id": item_id}

@app.delete(path, **kwargs)

Define a DELETE endpoint.

@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    return {"message": "Item deleted"}

@app.options(path, **kwargs)

Define an OPTIONS endpoint.

@app.head(path, **kwargs)

Define a HEAD endpoint.

@app.trace(path, **kwargs)

Define a TRACE endpoint.

add_api_route()

add_api_route(path, endpoint, **kwargs)

Add an API route programmatically.

path · str · required

URL path for the route.

endpoint · Callable · required

The endpoint function to call.

methods · list[str] | None

HTTP methods for this route (e.g., ["GET", "POST"]).

response_model · Any

Pydantic model for response validation and serialization.

status_code · int | None

Default status code for the response.

tags · list[str | Enum] | None

Tags for OpenAPI documentation.

dependencies · Sequence[Depends] | None

List of dependencies for this route.

summary · str | None

Short summary for OpenAPI documentation.

description · str | None

Detailed description for OpenAPI documentation.

app.add_api_route(
    "/items/",
    read_items,
    methods=["GET"],
    tags=["items"],
    summary="List all items"
)

include_router()

include_router(router, *, prefix="", tags=None, dependencies=None, **kwargs)

Include an APIRouter in the application.

router · APIRouter · required

The APIRouter to include.

prefix · str · default: ""

URL path prefix for all routes in the router.

tags · list[str | Enum] | None

Tags to be applied to all routes in the router.

dependencies · Sequence[Depends] | None

Dependencies to be applied to all routes in the router.

deprecated · bool | None

Mark all routes in the router as deprecated.

include_in_schema · bool · default: "True"

Include routes in OpenAPI schema.

from fastapi import FastAPI
from .routers import users, items

app = FastAPI()

app.include_router(
    users.router,
    prefix="/users",
    tags=["users"],
    dependencies=[Depends(get_token_header)],
)
app.include_router(items.router, prefix="/items", tags=["items"])

add_middleware()

add_middleware(middleware_class, **options)

Add middleware to the application.

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

exception_handler()

@app.exception_handler(exception_class)

Register a custom exception handler.

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

class CustomException(Exception):
    pass

@app.exception_handler(CustomException)
async def custom_exception_handler(request: Request, exc: CustomException):
    return JSONResponse(
        status_code=400,
        content={"message": "Custom error occurred"},
    )

openapi()

openapi()

Generate and return the OpenAPI schema.

schema = app.openapi()

websocket()

@app.websocket(path)

Define a WebSocket endpoint.

from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Message text was: {data}")

Attributes

state · State

A state object for the application. The same object for the entire application.

dependency_overrides · dict[Callable, Callable]

A dictionary with overrides for dependencies, useful for testing.

app.dependency_overrides[get_db] = get_test_db

router · APIRouter

The internal router instance.

routes · list[BaseRoute]

List of all registered routes.

openapi_schema · dict[str, Any] | None

The cached OpenAPI schema.

openapi_version · str

The OpenAPI version string (default: “3.1.0”).

app.openapi_version = "3.0.2"

webhooks · APIRouter

The webhooks router for OpenAPI webhooks documentation.

Example

from fastapi import FastAPI, Depends
from pydantic import BaseModel

app = FastAPI(
    title="My API",
    description="This is a very fancy API",
    version="1.0.0",
    docs_url="/documentation",
)

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = False

@app.get("/")
async def read_root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

@app.post("/items/")
async def create_item(item: Item):
    return item

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)