Автоматическая Swagger и ReDoc документация в FastAPI

Как FastAPI автоматически генерирует документацию (Swagger, ReDoc)?

FastAPI строит OpenAPI-схему на основе объявленных маршрутов, type hints, Pydantic-моделей, параметров и response models. По этой схеме он автоматически показывает интерактивный Swagger UI по адресу /docs и документацию ReDoc по адресу /redoc.

Подробный ответ

На чём основана документация

FastAPI анализирует endpoints приложения: их пути, HTTP-методы, параметры, Pydantic-модели, типы ответов, status codes и описание. На основе этой информации он формирует спецификацию OpenAPI.

Swagger UI и ReDoc

/docs — интерактивный интерфейс Swagger UI, где можно изучать и отправлять запросы к API из браузера;
/redoc — альтернативный интерфейс ReDoc для просмотра документации;
/openapi.json — JSON-представление OpenAPI-схемы.

Как улучшить описание endpoint

Можно указывать response model, tags, summary, description, status code и другие параметры в декораторе. Эти данные попадут в документацию.

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()


class ArticleOut(BaseModel):
    id: int
    title: str


@app.get(
    '/articles/{article_id}',
    response_model=ArticleOut,
    tags=['Articles'],
    summary='Получить статью',
    status_code=status.HTTP_200_OK,
)
def get_article(article_id: int):
    return {'id': article_id, 'title': 'FastAPI basics'}

Почему это полезно

Документация поддерживается рядом с кодом и обновляется при изменении API-контракта. Клиенты могут быстро увидеть доступные endpoints, обязательные параметры, форматы запросов и ответов.

Как ответить на собеседовании

FastAPI автоматически строит OpenAPI-схему из маршрутов, типов и Pydantic-моделей. На её основе по умолчанию доступны Swagger UI на /docs и ReDoc на /redoc; я дополняю документацию через response_model, tags, summary и описания endpoint.