FastAPI: Configure Endpoints with Decorators

Why it exists

Path operation decorators provide a clean, declarative way to attach metadata and configuration to an API endpoint. This separates the API protocol details, like status codes or documentation text, from the business logic inside the endpoint function, keeping the code cleaner.

The mental model

Think of a path operation decorator (@app.get, @app.post) as a label maker for your API endpoint function. You're not just giving it a URL path; you're attaching extra, machine-readable labels that FastAPI uses to generate documentation and configure the HTTP response.

How it works

When you define a route like @app.post("/items/", status_code=201, tags=["items"]), FastAPI reads these arguments directly from the decorator. It uses status_code to set the default HTTP status for successful responses. It uses tags to group this endpoint with others under the "items" heading in the auto-generated OpenAPI docs. Other parameters like summary, description, and deprecated also directly populate the OpenAPI schema, making your API self-documenting.

When to use it

Use decorator arguments any time you need to customize an endpoint's static configuration. Common uses include: setting a creation status code (status_code=201 for a POST), organizing a large API with tags, providing a clear summary for the docs, or gracefully retiring an old endpoint with deprecated=True.

When not to use it

These parameters are for static configuration. Do not use them for logic that needs to change based on the request's input. For example, if a function might return a 200 or a 202 status code based on some condition, you should handle that logic inside your function by returning a Response object directly. The decorator only sets the default for the "happy path".

One canonical example

To create an endpoint that adds a new item, returns a 201 Created status, and is grouped under "items" in the API docs, you would write:

from fastapi import FastAPI, status
app = FastAPI()

@app.post("/items/", status_code=status.HTTP_201_CREATED, tags=["items"])

async def create_item(name: str):
return {"name": name}

This configures the endpoint's documentation and default success response without adding any logic inside the create_item function itself.