MessageGateway/docs/api/decorators.md

# Декораторы API

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

## Декораторы

### `@require_api_key`

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

**Использование:**
```python
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`

**Пример:**
```python
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).

**Использование:**
```python
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 для надежного скрытия
- Используется для скрытия внутренних эндпоинтов от публичной документации
- Полезно для отладочных эндпоинтов и административных функций

**Пример:**
```python
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]:
    ...
```

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

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

```python
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 для управления группами](groups.md)
- Подробная документация по отладочным эндпоинтам: см. [API для отладки](debug.md)

---

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