319 lines
12 KiB
Markdown
319 lines
12 KiB
Markdown
# Документация API
|
||
|
||
Эта документация описывает все доступные эндпоинты API для приложения, включая методы, параметры, ответы и примеры использования. API разделено на три группы маршрутов: /api/auth, /api/settings и /api/dashboard. Большинство эндпоинтов, кроме /api/auth/login, требуют авторизации через Bearer-токен, который можно получить через эндпоинт логина.
|
||
|
||
## Общая информация
|
||
|
||
- **Базовый URL**: http://192.168.200.111:8000
|
||
- **Авторизация**: Большинство эндпоинтов требуют заголовок `Authorization: Bearer <token>` или query-параметр `token=<token>`. Токен получается через /api/auth/login.
|
||
- **Формат ответов**: JSON.
|
||
- **Коды ошибок**:
|
||
- 401 Unauthorized: Требуется авторизация или токен недействителен.
|
||
- 500 Internal Server Error: Ошибка на сервере.
|
||
|
||
## Получение токена авторизации
|
||
|
||
Для доступа к защищённым эндпоинтам необходимо получить Bearer-токен через эндпоинт /api/auth/login.
|
||
|
||
- **Эндпоинт**: POST /api/auth/login
|
||
- **Описание**: Аутентифицирует пользователя и возвращает сессионный токен.
|
||
- **Тело запроса (JSON)**:
|
||
```
|
||
{
|
||
"username": "string",
|
||
"password": "string"
|
||
}
|
||
```
|
||
- **Ответ**:
|
||
|
||
- Успех (200):
|
||
```
|
||
{
|
||
"access_token": "string",
|
||
"token_type": "bearer"
|
||
}
|
||
```
|
||
- Ошибка (401):
|
||
```
|
||
{
|
||
"detail": "Неверные учетные данные"
|
||
}
|
||
```
|
||
|
||
- **Пример**:
|
||
|
||
```
|
||
curl -X POST http://192.168.200.111:8000/api/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username": "admin", "password": "admin"}'
|
||
```
|
||
|
||
Результат (пример):
|
||
|
||
```
|
||
{
|
||
"access_token": "123e4567-e89b-12d3-a456-426614174000",
|
||
"token_type": "bearer"
|
||
}
|
||
```
|
||
|
||
Сохраните `access_token` для использования в других запросах.
|
||
|
||
## Эндпоинты /api/auth
|
||
|
||
1. **Получение информации о текущем пользователе**
|
||
|
||
- **Эндпоинт**: GET /api/auth/me
|
||
- **Описание**: Возвращает информацию о текущем пользователе на основе предоставленного токена. Если токен отсутствует или недействителен, возвращает неаутентифицированный статус.
|
||
- **Параметры запроса**:
|
||
- authorization (опционально, строка): Заголовок Authorization: Bearer <token>.
|
||
- token_param (опционально, строка): Query-параметр token=<token>.
|
||
- **Ответ**:
|
||
|
||
- Успех (200):
|
||
```
|
||
{
|
||
"username": "string",
|
||
"is_authenticated": true
|
||
}
|
||
```
|
||
- Неаутентифицирован (200):
|
||
```
|
||
{
|
||
"username": "",
|
||
"is_authenticated": false
|
||
}
|
||
```
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X GET http://192.168.200.111:8000/api/auth/me \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "accept: application/json"
|
||
```
|
||
|
||
2. **Выход из системы**
|
||
|
||
- **Эндпоинт**: POST /api/auth/logout
|
||
- **Описание**: Завершает сессию пользователя, удаляя токен.
|
||
- **Параметры запроса**:
|
||
- authorization (опционально, строка): Заголовок Authorization: Bearer <token>.
|
||
- token_param (опционально, строка): Query-параметр token=<token>.
|
||
- **Ответ**:
|
||
|
||
- Успех (200):
|
||
```
|
||
{
|
||
"status": "success",
|
||
"message": "Выход выполнен успешно"
|
||
}
|
||
```
|
||
- Нет сессии (200):
|
||
```
|
||
{
|
||
"status": "success",
|
||
"message": "Нет активной сессии"
|
||
}
|
||
```
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X POST http://192.168.200.111:8000/api/auth/logout \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "accept: application/json"
|
||
```
|
||
|
||
## Эндпоинты /api/settings
|
||
|
||
1. **Получение всех настроек**
|
||
|
||
- **Эндпоинт**: GET /api/settings
|
||
- **Описание**: Возвращает все настройки приложения (VAD, system, STT, commands, auth).
|
||
- **Ответ**:
|
||
|
||
- Успех (200): Объект с полями vad, system, stt, commands, auth (см. модели в коде).
|
||
- Ошибка (401): {"detail": "Не авторизован"}
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X GET http://192.168.200.111:8000/api/settings \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "accept: application/json"
|
||
```
|
||
|
||
2. **Обновление настроек VAD**
|
||
|
||
- **Эндпоинт**: PUT /api/settings/vad
|
||
- **Описание**: Обновляет настройки VAD.
|
||
- **Тело запроса (JSON)**: Объект VADSettings (см. модель в коде).
|
||
- **Ответ**:
|
||
|
||
- Успех (200): Обновлённый объект VADSettings.
|
||
- Ошибка (401): {"detail": "Не авторизован"}
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X PUT http://192.168.200.111:8000/api/settings/vad \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"mode": 1, "sample_rate": 16000, ...}'
|
||
```
|
||
|
||
(Аналогично для /system, /stt, /commands, /auth — обновление соответствующих настроек.)
|
||
|
||
3. **Перезапуск VAD и STT**
|
||
|
||
- **Эндпоинт**: POST /api/settings/restart
|
||
- **Описание**: Перезапускает VAD и STT с новыми настройками.
|
||
- **Ответ**:
|
||
|
||
- Успех (200):
|
||
```
|
||
{
|
||
"status": "success",
|
||
"message": "VAD и STT перезапущены"
|
||
}
|
||
```
|
||
- Ошибка (401): {"detail": "Не авторизован"}
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X POST http://192.168.200.111:8000/api/settings/restart \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "accept: application/json"
|
||
```
|
||
|
||
## Эндпоинты /api/dashboard
|
||
|
||
1. **Получение данных о речи и энергии**
|
||
|
||
- **Эндпоинт**: GET /api/dashboard/speech-data
|
||
- **Описание**: Возвращает текущие данные о речи и энергии, включая расширенные метрики VAD и STT.
|
||
- **Ответ**:
|
||
|
||
- Успех (200):
|
||
```
|
||
{
|
||
"state": "string",
|
||
"speech_prob": 0.0,
|
||
"energy": 0.0,
|
||
"energy_threshold": 0.0,
|
||
"speech_detected": false,
|
||
"continuous_frames": 0,
|
||
"gain": 1.0,
|
||
"noise_floor": 0.0,
|
||
"stt_model_path": "string",
|
||
"stt_commands_count": 0
|
||
}
|
||
```
|
||
- Ошибка (401): {"detail": "Не авторизован"}
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X GET http://192.168.200.111:8000/api/dashboard/speech-data \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "accept: application/json"
|
||
```
|
||
|
||
2. **Получение последних распознанных фраз**
|
||
|
||
- **Эндпоинт**: GET /api/dashboard/recent-phrases
|
||
- **Описание**: Возвращает список последних распознанных фраз (до указанного лимита).
|
||
- **Параметры запроса**:
|
||
- limit (опционально, целое число, по умолчанию 10): Максимальное количество фраз.
|
||
- **Ответ**:
|
||
|
||
- Успех (200):
|
||
```
|
||
[
|
||
{
|
||
"text": "Пример фразы",
|
||
"timestamp": "2025-10-13T11:13:00",
|
||
"is_command": true
|
||
},
|
||
...
|
||
]
|
||
```
|
||
- Ошибка (401): {"detail": "Не авторизован"}
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X GET http://192.168.200.111:8000/api/dashboard/recent-phrases?limit=5 \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "accept: application/json"
|
||
```
|
||
|
||
3. **Получение статистики системы**
|
||
|
||
- **Эндпоинт**: GET /api/dashboard/stats
|
||
- **Описание**: Возвращает расширенную статистику работы системы (время работы, количество распознанных фраз, системная нагрузка и т.д.).
|
||
- **Ответ**:
|
||
|
||
- Успех (200):
|
||
```
|
||
{
|
||
"uptime": "0:00:00",
|
||
"recognized_phrases_count": 0,
|
||
"commands_executed_count": 0,
|
||
"system_load": {
|
||
"cpu_percent": 0.0,
|
||
"memory_percent": 0.0,
|
||
"temperature": 0.0
|
||
},
|
||
"total_speech_frames": 0,
|
||
"avg_speech_prob": 0.0,
|
||
"vad_initialized": true,
|
||
"stt_initialized": true
|
||
}
|
||
```
|
||
- Ошибка (401): {"detail": "Не авторизован"}
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X GET http://192.168.200.111:8000/api/dashboard/stats \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "accept: application/json"
|
||
```
|
||
|
||
4. **Получение данных о нагрузке системы**
|
||
|
||
- **Эндпоинт**: GET /api/dashboard/sys-monitor
|
||
- **Описание**: Возвращает данные о нагрузке системы (CPU, память, температура).
|
||
- **Ответ**:
|
||
|
||
- Успех (200):
|
||
```
|
||
{
|
||
"cpu_percent": 0.0,
|
||
"memory_percent": 0.0,
|
||
"temperature": 0.0
|
||
}
|
||
```
|
||
- Ошибка (401): {"detail": "Не авторизован"}
|
||
- Ошибка (500): {"detail": "Описание ошибки"}
|
||
|
||
- **Пример**:
|
||
```
|
||
curl -X GET http://192.168.200.111:8000/api/dashboard/sys-monitor \
|
||
-H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
|
||
-H "accept: application/json"
|
||
```
|
||
|
||
## Замечания
|
||
|
||
- **Авторизация**: Все эндпоинты, кроме /api/auth/login, требуют токен, полученный через /api/auth/login. Токен можно передать:
|
||
- В заголовке: `Authorization: Bearer <token>`
|
||
- В query-параметре: `?token=<token>`
|
||
- **Безопасность**: Пароли в настройках хранятся в открытом виде. Рекомендуется использовать хэширование (например, bcrypt) для auth.password.
|
||
- **Хранение сессий**: Токены хранятся в памяти (ACTIVE_SESSIONS). Для продакшена используйте Redis или другую базу данных.
|
||
- **Ограничения**: Токены не имеют срока действия. Рекомендуется добавить expiration (например, хранить timestamp в ACTIVE_SESSIONS).
|
||
- **Обновления**: Документация актуализирована на 13 октября 2025 года. Добавлены новые поля в /speech-data, новый эндпоинт /sys-monitor и расширенная структура для /stats.
|