Swagger и OpenAPI в FastAPI

FastAPI автоматически собирает документацию из маршрутов, типов и Pydantic-моделей.
Поэтому /docs — не отдельный текст, а наглядное представление контракта твоего API.

Для ученика Swagger UI работает как лаборатория: можно увидеть параметры, отправить
настоящий запрос и сразу проверить status code и тело ответа.

Что открыть после запуска

• http://127.0.0.1:8000/docs — Swagger UI с кнопкой Try it out;
• http://127.0.0.1:8000/redoc — документация в формате справочника;
• http://127.0.0.1:8000/openapi.json — исходная OpenAPI-схема.

Swagger UI и ReDoc читают одну схему. Если интерфейс показывает что-то неправильно,
проверь сначала /openapi.json.

Проверь endpoint через Swagger

1. Раскрой нужный endpoint и нажми Try it out.
2. Заполни path, query или body-параметры.
3. Нажми Execute.
4. Сравни Request URL, status code и response body с заданием.
5. Отправь некорректные данные и изучи ответ 422.

Это удобная ручная проверка, но не замена автоматическим тестам.

Добавь информацию об API

from fastapi import FastAPI

app = FastAPI(
    title="Task Manager API",
    summary="API учебного менеджера задач",
    description="Создание, поиск, обновление и удаление задач.",
    version="1.0.0",
    contact={"name": "Поддержка", "email": "support@example.com"},
)

version относится к твоему API, а не к FastAPI. description поддерживает Markdown.

Опиши и сгруппируй маршруты

from fastapi import APIRouter, status

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


@router.get(
    "/",
    summary="Получить список задач",
    description="Возвращает задачи с фильтрацией и пагинацией.",
    response_description="Список найденных задач",
    status_code=status.HTTP_200_OK,
)
def list_tasks():
    return []


app.include_router(router)

summary коротко называет действие, description объясняет важные условия, а тег
объединяет операции одного ресурса. Если router не подключён через include_router,
его endpoints не появятся в документации.

Покажи запрос и ответ

from pydantic import BaseModel, Field


class TaskCreate(BaseModel):
    title: str = Field(
        min_length=3,
        max_length=120,
        description="Короткое название задачи",
        examples=["Написать тесты"],
    )


class TaskRead(TaskCreate):
    id: int


@router.post("/", response_model=TaskRead, status_code=201)
def create_task(task: TaskCreate):
    return {"id": 1, **task.model_dump()}

Field добавляет ограничения и пример входных данных. response_model описывает и
проверяет успешный ответ, а также скрывает поля, которых нет в публичной модели.
Используй современный вариант examples=[...], а не одиночный example.

Ожидаемые ошибки тоже можно показать:

@router.get(
    "/{task_id}",
    response_model=TaskRead,
    responses={404: {"description": "Задача не найдена"}},
)
def get_task(task_id: int):
    ...

Документация не создаёт ошибку автоматически: маршрут действительно должен вернуть
404, а тест — подтвердить это поведение.

Авторизация в Swagger UI

При использовании OAuth2PasswordBearer Swagger показывает кнопку Authorize:

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/token")

Security dependency должна участвовать в маршруте. tokenUrl указывает на endpoint,
который выдаёт токен.

Частые проблемы

• Нет схемы ответа — добавь возвращаемый тип или response_model.
• Параметр попал в query вместо body — передавай тело как Pydantic-модель.
• Endpoint отсутствует — проверь include_router.
• Пример не виден — используй examples=[...] или json_schema_extra.
• Authorize отсутствует — подключи security dependency к маршруту.
• Видна старая схема — перезапусти сервер и обнови страницу без кеша.

Перед завершением выполни через /docs один успешный и один ошибочный запрос. Убедись,
что видны ограничения входных данных, успешный статус, схема ответа и ожидаемые ошибки.

Официальная документация

• Метаданные и URL документации
• Примеры входных данных
• Модели ответа