MessageGateway/docs/api/decorators.md

Декораторы API

В проекте Message Gateway используются декораторы для упрощения работы с API и обеспечения безопасности.

Декораторы

@require_api_key

Декоратор для пометки эндпоинта как требующего API ключ для авторизации.

Использование:

from app.core.auth import require_api_key, require_api_key_dependency

@require_api_key
@router.post("/endpoint", dependencies=[require_api_key_dependency])
async def my_endpoint(request: Request, ...):
    ...

Примечания:

• Декоратор используется только для пометки функции
• Фактическая проверка API ключа выполняется через dependencies=[require_api_key_dependency]
• Это обеспечивает отображение замочка в Swagger UI
• API ключ настраивается в переменной окружения API_KEY в файле .env
• API ключ передается в заголовке X-API-Key

Пример:

from app.core.auth import require_api_key, require_api_key_dependency
from fastapi import APIRouter, Request, Body

router = APIRouter(prefix="/api/v1/groups", tags=["groups"])

@require_api_key
@router.post(
    "",
    name="Создать группу",
    dependencies=[require_api_key_dependency]
)
async def create_group(
    request: Request,
    body: CreateGroupRequest = Body(...)
) -> Dict[str, Any]:
    ...

@hide_from_api

Декоратор для скрытия эндпоинта из API документации (Swagger UI).

Использование:

from app.core.auth import hide_from_api

@hide_from_api
@router.post("/debug/dump", include_in_schema=False)
async def debug_endpoint(...):
    ...

Примечания:

• Декоратор помечает функцию как скрытую от API
• Эндпоинт все еще будет работать, но не будет отображаться в Swagger UI
• Рекомендуется использовать вместе с параметром include_in_schema=False в декораторе route для надежного скрытия
• Используется для скрытия внутренних эндпоинтов от публичной документации
• Полезно для отладочных эндпоинтов и административных функций

Пример:

from app.core.auth import hide_from_api
from fastapi import APIRouter, Body

router = APIRouter(prefix="/api/v1/debug", tags=["debug"])

@hide_from_api
@router.post(
    "/dump",
    name="JSON Debug dump",
    include_in_schema=False,  # Скрываем эндпоинт из Swagger UI
    response_model=Dict[str, Any]
)
async def dump_request(
    dump: Dict[str, Any] = Body(...)
) -> Dict[str, Any]:
    ...

Комбинирование декораторов

Декораторы можно комбинировать для более сложных сценариев:

from app.core.auth import require_api_key, require_api_key_dependency, hide_from_api

@require_api_key
@hide_from_api
@router.post(
    "/internal/admin",
    dependencies=[require_api_key_dependency],
    include_in_schema=False
)
async def internal_admin_endpoint(request: Request, ...):
    ...

В этом примере:

• Эндпоинт требует API ключ для доступа
• Эндпоинт скрыт из Swagger UI
• Эндпоинт доступен только для администраторов с правильным API ключом

Примечания

• Декораторы применяются снизу вверх (от функции к верхнему декоратору)
• Порядок декораторов важен: сначала применяется декоратор route (@router.post), затем декораторы авторизации и скрытия
• Декораторы не изменяют функциональность эндпоинта, они только добавляют метаданные или проверки
• Все декораторы определены в модуле app.core.auth

Дополнительная информация

• Подробная документация по API ключам: см. API для управления группами
• Подробная документация по отладочным эндпоинтам: см. API для отладки

---

Автор: Сергей Антропов
Сайт: https://devops.org.ru