FastAPI OpenAPI Customization: Tags, Examples & Schema That Survive Production

# io.thecodeforge — Python tutorial

from fastapi import APIRouter, FastAPI

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/")
async def list_users():
    return [{"id": 1, "name": "Alice"}]

app = FastAPI()
app.include_router(router)

# Output when hitting /docs: endpoints grouped under "users" tag

# io.thecodeforge — Python tutorial

from fastapi import FastAPI, Body
from pydantic import BaseModel, Field

class OrderItem(BaseModel):
    product_id: str = Field(..., example="prod_123", description="Product SKU")
    quantity: int = Field(..., ge=1, example=2, description="Number of items")

app = FastAPI()

@app.post("/checkout")
async def checkout(
    items: list[OrderItem] = Body(
        ...,
        openapi_examples={
            "single_item": {
                "summary": "One item order",
                "value": [{"product_id": "prod_123", "quantity": 1}]
            },
            "multi_item": {
                "summary": "Multiple items",
                "value": [
                    {"product_id": "prod_123", "quantity": 2},
                    {"product_id": "prod_456", "quantity": 1}
                ]
            }
        }
    )
):
    return {"status": "ok", "count": len(items)}

# Run: uvicorn examples_checkout:app --reload

# io.thecodeforge — Python tutorial

from pydantic import BaseModel, Field
from typing import Optional

class UserResponse(BaseModel):
    id: int = Field(..., example=1234567890, json_schema_extra={"format": "int64"})
    name: str = Field(...)
    created_at: str = Field(..., description="ISO 8601 timestamp")

    class Config:
        schema_extra = {
            "example": {
                "id": 1234567890,
                "name": "Alice",
                "created_at": "2024-01-15T10:30:00Z"
            }
        }

# The generated OpenAPI schema will include format: int64 for id and an example at model level.

# io.thecodeforge — Python tutorial

from fastapi import FastAPI

app = FastAPI()

@app.get("/users", operation_id="users_list")
async def get_users():
    return [{"id": 1}]

@app.post("/users", operation_id="users_create")
async def create_user():
    return {"id": 2}

# OpenAPI spec will have operationId: users_list and users_create

# io.thecodeforge — Python tutorial

from fastapi import FastAPI

app = FastAPI(
    title="Checkout API",
    version="2.1.0",
    description="Handles orders and payments for the e-commerce platform.",
    contact={
        "name": "API Support",
        "email": "api@example.com"
    },
    license_info={
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT"
    },
    openapi_tags=[
        {
            "name": "users",
            "description": "User management endpoints"
        },
        {
            "name": "orders",
            "description": "Order processing and history"
        }
    ]
)

@app.get("/users", tags=["users"])
async def get_users():
    return []

@app.get("/orders", tags=["orders"])
async def get_orders():
    return []

# io.thecodeforge — Python tutorial

from fastapi import FastAPI, Body
from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(..., example="widget")
    price: float = Field(..., example=9.99)

app = FastAPI()

# Pitfall: openapi_examples on Body but Item already has field-level examples
@app.post("/items")
async def create_item(
    item: Item = Body(
        ...,
        openapi_examples={
            "default": {
                "summary": "Default item",
                "value": {"name": "gadget", "price": 19.99}
            }
        }
    )
):
    return item

# The generated schema will have both field-level examples and the body-level example.
# Some code generators may pick the body-level example and ignore field-level ones.

# io.thecodeforge — Python tutorial

from fastapi.testclient import TestClient
from your_app import app

client = TestClient(app)

def test_openapi_spec():
    response = client.get("/openapi.json")
    assert response.status_code == 200
    spec = response.json()
    
    # Check that tags are present
    assert "users" in [tag["name"] for tag in spec.get("tags", [])]
    
    # Check that operation IDs are set
    assert spec["paths"]["/users"]["get"]["operationId"] == "users_list"
    
    # Check that examples exist
    assert "example" in spec["components"]["schemas"]["OrderItem"]["properties"]["product_id"]

# Run with: pytest test_openapi.py