Path Operation Advanced Configuration

Learn about advanced path operation decorator parameters including operation_id, callbacks, OpenAPI extras, and more

Overview

FastAPI provides advanced configuration options for path operation decorators that give you fine-grained control over your API’s behavior and OpenAPI documentation.

Operation ID

You can set a custom operation ID for your path operation. This is particularly useful when generating API clients, as the operation ID becomes the function name in the generated client.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/", operation_id="some_specific_id_you_define")
async def read_items():
    return [{"item_id": "Foo"}]

Make sure your operation_id is unique across all operations in your API. FastAPI won’t validate this for you.

Summary and Description

You can add a summary and description to your path operations:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()

@app.post("/items/", summary="Create an item")
async def create_item(item: Item) -> Item:
    """
    Create an item with all the information:

    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    """
    return item

The docstring becomes the description in the OpenAPI schema, while the summary parameter provides a short title.

Response Description

Customize the description of the successful response:

@app.post(
    "/items/",
    response_description="The created item"
)
async def create_item(item: Item) -> Item:
    return item

The default response_description is “Successful Response”.

Deprecation

Mark an endpoint as deprecated:

@app.get("/items/", deprecated=True)
async def read_items():
    return [{"item_id": "Foo"}]

This will show the endpoint as deprecated in the interactive API docs.

Tags

Organize your endpoints with tags:

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"item_id": "Foo"}]

@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

Tags group related endpoints together in the API documentation.

Include in Schema

Exclude an endpoint from the OpenAPI schema:

@app.get("/items/", include_in_schema=False)
async def read_items():
    return [{"item_id": "Foo"}]

This is useful for internal endpoints that you don’t want to expose in your API documentation.

OpenAPI Extra

Add custom OpenAPI fields that aren’t directly supported:

@app.get(
    "/items/",
    openapi_extra={
        "x-custom-field": "custom-value",
        "externalDocs": {
            "description": "External documentation",
            "url": "https://example.com/docs"
        }
    }
)
async def read_items():
    return [{"item_id": "Foo"}]

The openapi_extra dictionary is merged into the OpenAPI schema for this path operation.

Generate Unique ID Function

Customize how operation IDs are generated:

from fastapi import FastAPI
from fastapi.routing import APIRoute

def custom_generate_unique_id(route: APIRoute) -> str:
    return f"{route.tags[0]}-{route.name}"

app = FastAPI(generate_unique_id_function=custom_generate_unique_id)

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"item_id": "Foo"}]

This is particularly useful when generating API clients, as it affects the generated function names.

Callbacks

Define OpenAPI callbacks for webhooks that your API will call:

from fastapi import APIRouter, FastAPI

app = FastAPI()

callback_router = APIRouter()

@callback_router.post("{$callback_url}/notification")
async def callback_notification(body: dict):
    pass

@app.post("/items/", callbacks=callback_router.routes)
async def create_item(callback_url: str | None = None):
    # Your endpoint logic here
    # After processing, your API would call the callback_url
    return {"message": "Item created"}

Callbacks are for documentation purposes in OpenAPI. You still need to implement the actual HTTP calls to the callback URLs in your endpoint logic.

Response Class

Specify the default response class for an endpoint:

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/items/", response_class=HTMLResponse)
async def read_items():
    return "<html><body><h1>Items</h1></body></html>"

See Custom Response Classes for more details.

All Parameters Together

Here’s an example using multiple advanced parameters:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post(
    "/items/",
    operation_id="create_new_item",
    summary="Create a new item",
    response_description="The newly created item",
    tags=["items"],
    deprecated=False,
    include_in_schema=True,
    openapi_extra={
        "x-api-version": "1.0"
    }
)
async def create_item(item: Item) -> Item:
    """
    Create an item with the following attributes:
    
    - **name**: The item name
    - **price**: The item price
    """
    return item