Add new file

rag/openapi.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""
+Настройка OpenAPI для RAG-сервера.
+Определяет теги, метаданные и примеры для автоматической документации.
+"""
+
+from typing import Dict, Any
+
+# Метаданные API
+API_METADATA = {
+    "title": "RAG-сервер Эфцекабот",
+    "version": "3.0.0",
+    "description": """
+## Единый RAG-сервер для платформы Эфцекабот
+
+Сервис предоставляет REST API для выполнения RAG-запросов, индексации документов,
+а также распознавания текста на изображениях (OCR) и транскрибации аудио.
+
+### Основные возможности
+
+- **RAG-запросы** – выполнение поиска по базе знаний с генерацией ответа.
+- **Индексация** – добавление документов в базу знаний.
+- **OCR** – распознавание текста на изображениях (JPEG, PNG, BMP, TIFF).
+- **Транскрибация** – преобразование речи в текст (OGG, WAV, MP3, AMR, M4A).
+
+### Аутентификация
+
+Все эндпоинты (кроме `/health`) требуют передачи API-ключа в заголовке `X-API-Key`.
+""",
+    "contact": {
+        "name": "Команда Эфцекабот",
+        "email": "support@fckbot.ru",
+        "url": "https://fckbot.ru",
+    },
+    "license": {
+        "name": "ISC License",
+    },
+}
+
+# Теги для группировки эндпоинтов в документации
+OPENAPI_TAGS = [
+    {
+        "name": "RAG",
+        "description": "Основные RAG-эндпоинты: запросы и индексация.",
+    },
+    {
+        "name": "Vision",
+        "description": "Распознавание текста на изображениях (OCR).",
+    },
+    {
+        "name": "Transcribe",
+        "description": "Транскрибация аудиофайлов (SaluteSpeech).",
+    },
+    {
+        "name": "Health",
+        "description": "Проверка состояния сервиса (без аутентификации).",
+    },
+]
+
+# Примеры для эндпоинтов (используются в документации)
+EXAMPLES = {
+    "query": {
+        "summary": "Пример RAG-запроса",
+        "value": {
+            "query": "Какое тактовое время установлено на линии?",
+            "user_jid": "user@example.com",
+            "room_jid": None,
+            "prompts": {},
+            "intent_override": None,
+            "last_file_path": None,
+            "last_file_text": None,
+        }
+    },
+    "index": {
+        "summary": "Пример индексации документа",
+        "value": {
+            "file_name": "example.docx",
+            "file_text": "Содержимое документа...",
+            "user_jid": "user@example.com",
+            "room_jid": "room@conference.example.com",
+            "is_global": False,
+            "title": "Пример документа",
+            "metadata": {"author": "Иван Иванов"},
+            "file_hash": "a1b2c3...",
+            "update_if_exists": True,
+        }
+    }
+}
+
+def get_openapi_config() -> Dict[str, Any]:
+    """
+    Возвращает конфигурацию OpenAPI для приложения FastAPI.
+    """
+    return {
+        "title": API_METADATA["title"],
+        "version": API_METADATA["version"],
+        "description": API_METADATA["description"],
+        "contact": API_METADATA.get("contact"),
+        "license_info": API_METADATA.get("license"),
+        "openapi_tags": OPENAPI_TAGS,
+    }