Initial commit: Message Gateway project

- FastAPI приложение для отправки мониторинговых алертов в мессенджеры
- Поддержка Telegram и MAX/VK
- Интеграция с Grafana, Zabbix, AlertManager
- Автоматическое создание тикетов в Jira
- Управление группами мессенджеров через API
- Декораторы для авторизации и скрытия эндпоинтов
- Подробная документация в папке docs/

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

docs/api/decorators.md

@@ -0,0 +1,128 @@
+# Декораторы 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
+