Swagger документация в FastAPI

FastAPI автоматически генерирует OpenAPI документацию из кода.

Доступ к документации

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

Метаданные приложения

from fastapi import FastAPI

app = FastAPI(
    title="Task Manager API",
    description="## API для управления задачами\n\nПоддерживает CRUD для задач и проектов.",
    version="1.0.0",
    contact={
        "name": "Поддержка",
        "email": "support@example.com",
    },
    license_info={"name": "MIT"},
)

Документирование endpoints

@app.get(
    "/tasks/",
    summary="Список задач",
    description="Возвращает все задачи текущего пользователя с пагинацией.",
    response_description="Список задач",
    tags=["Tasks"],
)
def list_tasks():
    ...

Теги для группировки

from fastapi import APIRouter

tasks_router = APIRouter(prefix="/tasks", tags=["Tasks"])
projects_router = APIRouter(prefix="/projects", tags=["Projects"])
auth_router = APIRouter(prefix="/auth", tags=["Authentication"])

app.include_router(tasks_router)
app.include_router(projects_router)
app.include_router(auth_router)

Документирование моделей

from pydantic import BaseModel, Field

class TaskCreate(BaseModel):
    title: str = Field(..., description="Заголовок задачи", example="Написать тесты")
    priority: int = Field(1, description="Приоритет от 1 до 3", ge=1, le=3)
    status: str = Field("todo", description="Статус задачи")

    model_config = {
        "json_schema_extra": {
            "example": {
                "title": "Написать тесты",
                "priority": 2,
                "status": "todo",
            }
        }
    }

Отключение документации

app = FastAPI(docs_url=None, redoc_url=None)  # только для продакшна

Аутентификация в Swagger

from fastapi.security import OAuth2PasswordBearer

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

@app.get("/tasks/")
def list_tasks(token: str = Depends(oauth2_scheme)):
    ...

В Swagger появится кнопка “Authorize” для ввода токена.