Как FastAPI автоматически генерирует OpenAPI-документацию (/docs и /redoc)?

Как FastAPI генерирует OpenAPI-документацию

FastAPI строит спецификацию OpenAPI 3.x автоматически в момент создания приложения. При каждом вызове @app.get(), @app.post() и т.д. фреймворк регистрирует маршрут и читает сигнатуру функции через inspect. Типы аргументов (Python type hints), Pydantic-модели, зависимости (Depends) и декораторы преобразуются в JSON Schema и записываются в объект openapi_schema.

Итоговый JSON доступен по адресу /openapi.json. Два встроенных HTML-маршрута отдают UI:

• /docs — Swagger UI (пакет swagger-ui-bundle из CDN)
• /redoc — ReDoc

Ключевые механизмы

• Параметры функции → поля parameters в операции OpenAPI.
• Pydantic BaseModel в аргументе → тело запроса (requestBody) со схемой.
• response_model= → секция responses["200"].
• Теги, summary, description берутся из декоратора и docstring функции.

Пример: кастомизация метаданных

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(
    title="My API",
    version="1.0.0",
    description="Описание API",
    openapi_url="/api/openapi.json",  # сменить URL схемы
    docs_url="/api/docs",             # сменить URL Swagger UI
    redoc_url=None,                   # отключить ReDoc
)

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

@app.post(
    "/items/",
    tags=["items"],
    summary="Создать товар",
    response_model=Item,
    status_code=201,
)
async def create_item(item: Item) -> Item:
    """Принимает JSON с полями name и price, возвращает созданный объект."""
    return item

Запустив uvicorn main:app --reload и открыв http://localhost:8000/api/docs, вы увидите автоматически построенную форму для POST /items/ с телом {"name": "...", "price": 0}.

Отключение или замена схемы

from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title=app.title,
        version=app.version,
        routes=app.routes,
    )
    # добавить security scheme
    schema["components"]["securitySchemes"] = {
        "BearerAuth": {"type": "http", "scheme": "bearer"}
    }
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi

Подводные камни

• Если передать openapi_url=None, то /docs и /redoc тоже перестанут работать — они зависят от схемы.
• Маршруты с include_in_schema=False не попадают в OpenAPI, но продолжают обрабатывать запросы.
• Схема кешируется в app.openapi_schema; если маршруты добавляются динамически после старта, они не отразятся без сброса кеша.
• Pydantic v2 меняет формат $defs вместо definitions — некоторые старые клиенты OpenAPI могут не распознать схему.
• Большие вложенные схемы сильно раздувают /openapi.json — следите за размером при сотнях моделей.
• CDN Swagger UI / ReDoc недоступны в закрытых сетях — используйте fastapi.staticfiles для self-hosted ресурсов.
• Параметры Depends() скрываются из документации; чтобы они отображались, нужно явно объявить их через Query() / Header().

• Описывать openapi docs только как термин и не показывать механизм на минимальном примере.
• Игнорировать ошибки, пустые данные, конкурентный доступ или границы транзакции.
• Не связывать поведение с официальным контрактом FastAPI и реальной эксплуатацией.

• Объясняет openapi docs через последовательность действий, а не через набор ключевых слов.
• Приводит короткий кодовый пример или production-сценарий с ожидаемым поведением.
• Называет хотя бы один риск: производительность, безопасность, транзакции, память или сопровождение.