FastAPI · Lesson 14 of 15

Custom OpenAPI and Docs

Tags, examples, description markdown and hiding routes from /docs.

Advanced
16 min read
3 objectives

Before this lessonLesson 13: API Security Hardening

What you will learn

Group routes with tags
Add examples
Customise the OpenAPI schema

Your Progress

0 of 15 lessons 0%

Lessons0 / 15
Completed0
Est. time left~ 4 hours

Create a free account to keep your progress on every device.

The automatic docs are a product surface. Tags, summaries and examples make them usable for the next person (including you in six months).

Tags and metadata

app = FastAPI(
    title="Tasks API",
    version="1.2.0",
    description="CRUD for personal tasks. Authenticate via `/token`.",
    openapi_tags=[
        {"name": "tasks", "description": "Create and list tasks"},
        {"name": "auth", "description": "Login and current user"},
    ],
)

@app.get("/tasks", tags=["tasks"], summary="List tasks", response_description="A page of tasks")
def list_tasks():
    ...

Examples on models

from pydantic import BaseModel, Field, ConfigDict

class TaskIn(BaseModel):
    model_config = ConfigDict(json_schema_extra={
        "examples": [{"title": "Write tests", "done": False}]
    })
    title: str = Field(..., min_length=1, max_length=100, description="Shown in the list")
    done: bool = False

Hide internal routes

@app.get("/internal/metrics", include_in_schema=False)
def metrics():
    return PlainTextResponse("ok")

You can also replace the schema entirely with app.openapi = custom_openapi if you need to inject a security scheme globally.

Up next · Lesson 15Production: Docker and ObservabilityUvicorn workers, health checks, structured logs and tracing.