1509 lines
43 KiB
YAML
1509 lines
43 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: ИИ-юрист
|
||
description: API для системы ИИ-юриста с RAG функциональностью
|
||
version: 1.0.0
|
||
contact:
|
||
name: API Support
|
||
|
||
servers:
|
||
- url: http://localhost:8000
|
||
description: Локальный сервер
|
||
- url: http://backend:8000
|
||
description: Docker контейнер
|
||
|
||
tags:
|
||
- name: users
|
||
description: Управление пользователями
|
||
- name: collections
|
||
description: Управление коллекциями документов
|
||
- name: documents
|
||
description: Управление документами
|
||
- name: conversations
|
||
description: Управление беседами
|
||
- name: messages
|
||
description: Управление сообщениями
|
||
- name: rag
|
||
description: RAG функциональность для ответов на вопросы
|
||
- name: admin
|
||
description: Административные функции
|
||
|
||
paths:
|
||
/:
|
||
get:
|
||
summary: Корневой эндпоинт
|
||
description: Информация об API
|
||
tags: []
|
||
responses:
|
||
'200':
|
||
description: Успешный ответ
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
message:
|
||
type: string
|
||
example: Добро пожаловать в API ИИ-юриста
|
||
version:
|
||
type: string
|
||
example: "1.0.0"
|
||
docs:
|
||
type: string
|
||
example: /docs
|
||
|
||
/health:
|
||
get:
|
||
summary: Проверка здоровья приложения
|
||
description: Проверка работоспособности API
|
||
tags: []
|
||
responses:
|
||
'200':
|
||
description: Сервис работает
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
example: ok
|
||
|
||
/api/v1/users:
|
||
post:
|
||
summary: Создать пользователя
|
||
description: Создание нового пользователя в системе
|
||
tags: [users]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserCreate'
|
||
responses:
|
||
'201':
|
||
description: Пользователь создан
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
'400':
|
||
$ref: '#/components/responses/BadRequest'
|
||
'500':
|
||
$ref: '#/components/responses/InternalServerError'
|
||
|
||
get:
|
||
summary: Получить список пользователей
|
||
description: Получить список всех пользователей с пагинацией
|
||
tags: [users]
|
||
parameters:
|
||
- name: skip
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 0
|
||
minimum: 0
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 100
|
||
minimum: 1
|
||
maximum: 1000
|
||
responses:
|
||
'200':
|
||
description: Список пользователей
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
|
||
/api/v1/users/me:
|
||
get:
|
||
summary: Получить информацию о текущем пользователе
|
||
description: Получить информацию о текущем аутентифицированном пользователе
|
||
tags: [users]
|
||
security:
|
||
- TelegramAuth: []
|
||
responses:
|
||
'200':
|
||
description: Информация о пользователе
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
|
||
/api/v1/users/telegram/{telegram_id}:
|
||
get:
|
||
summary: Получить пользователя по Telegram ID
|
||
description: Получить информацию о пользователе по его Telegram ID
|
||
tags: [users]
|
||
parameters:
|
||
- name: telegram_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: Информация о пользователе
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/users/telegram/{telegram_id}/increment-questions:
|
||
post:
|
||
summary: Увеличить счетчик использованных вопросов
|
||
description: Увеличить счетчик использованных вопросов для пользователя
|
||
tags: [users]
|
||
parameters:
|
||
- name: telegram_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: Счетчик обновлен
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/users/telegram/{telegram_id}/activate-premium:
|
||
post:
|
||
summary: Активировать premium статус
|
||
description: Активировать premium подписку для пользователя
|
||
tags: [users]
|
||
parameters:
|
||
- name: telegram_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: days
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 30
|
||
minimum: 1
|
||
responses:
|
||
'200':
|
||
description: Premium активирован
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/users/{user_id}:
|
||
get:
|
||
summary: Получить пользователя по ID
|
||
description: Получить информацию о пользователе по его UUID
|
||
tags: [users]
|
||
parameters:
|
||
- name: user_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: Информация о пользователе
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
put:
|
||
summary: Обновить пользователя
|
||
description: Обновить информацию о пользователе
|
||
tags: [users]
|
||
parameters:
|
||
- name: user_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserUpdate'
|
||
responses:
|
||
'200':
|
||
description: Пользователь обновлен
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
delete:
|
||
summary: Удалить пользователя
|
||
description: Удалить пользователя из системы
|
||
tags: [users]
|
||
parameters:
|
||
- name: user_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'204':
|
||
description: Пользователь удален
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/collections:
|
||
post:
|
||
summary: Создать коллекцию
|
||
description: Создать новую коллекцию документов
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CollectionCreate'
|
||
responses:
|
||
'201':
|
||
description: Коллекция создана
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CollectionResponse'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
|
||
get:
|
||
summary: Получить список коллекций
|
||
description: Получить список коллекций, доступных текущему пользователю
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: skip
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 0
|
||
minimum: 0
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 100
|
||
minimum: 1
|
||
maximum: 1000
|
||
responses:
|
||
'200':
|
||
description: Список коллекций
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/CollectionResponse'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
|
||
/api/v1/collections/{collection_id}:
|
||
get:
|
||
summary: Получить коллекцию по ID
|
||
description: Получить информацию о коллекции
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: Информация о коллекции
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CollectionResponse'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
put:
|
||
summary: Обновить коллекцию
|
||
description: Обновить информацию о коллекции (только владелец)
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CollectionUpdate'
|
||
responses:
|
||
'200':
|
||
description: Коллекция обновлена
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CollectionResponse'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
delete:
|
||
summary: Удалить коллекцию
|
||
description: Удалить коллекцию (только владелец)
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'204':
|
||
description: Коллекция удалена
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/collections/{collection_id}/access:
|
||
post:
|
||
summary: Предоставить доступ к коллекции
|
||
description: Предоставить доступ пользователю к коллекции (только владелец)
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CollectionAccessGrant'
|
||
responses:
|
||
'201':
|
||
description: Доступ предоставлен
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CollectionAccessResponse'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
|
||
get:
|
||
summary: Получить список пользователей с доступом
|
||
description: Получить список пользователей, имеющих доступ к коллекции
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: Список пользователей с доступом
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/CollectionAccessListResponse'
|
||
|
||
/api/v1/collections/{collection_id}/access/{user_id}:
|
||
delete:
|
||
summary: Отозвать доступ к коллекции
|
||
description: Отозвать доступ пользователя к коллекции (только владелец)
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: user_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'204':
|
||
description: Доступ отозван
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
|
||
/api/v1/collections/{collection_id}/access/telegram/{telegram_id}:
|
||
post:
|
||
summary: Предоставить доступ по Telegram ID
|
||
description: Предоставить доступ пользователю к коллекции по Telegram ID
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: telegram_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'201':
|
||
description: Доступ предоставлен
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CollectionAccessResponse'
|
||
|
||
delete:
|
||
summary: Отозвать доступ по Telegram ID
|
||
description: Отозвать доступ пользователя к коллекции по Telegram ID
|
||
tags: [collections]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: telegram_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'204':
|
||
description: Доступ отозван
|
||
|
||
/api/v1/documents:
|
||
post:
|
||
summary: Создать документ
|
||
description: Создать новый документ в коллекции
|
||
tags: [documents]
|
||
security:
|
||
- TelegramAuth: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/DocumentCreate'
|
||
responses:
|
||
'201':
|
||
description: Документ создан
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/DocumentResponse'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
|
||
/api/v1/documents/upload:
|
||
post:
|
||
summary: Загрузить документ
|
||
description: Загрузить и распарсить PDF документ или изображение с автоматической индексацией
|
||
tags: [documents]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
file:
|
||
type: string
|
||
format: binary
|
||
required:
|
||
- file
|
||
responses:
|
||
'201':
|
||
description: Документ загружен и проиндексирован
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/DocumentResponse'
|
||
'400':
|
||
description: Неподдерживаемый формат файла
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Error'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
|
||
/api/v1/documents/{document_id}:
|
||
get:
|
||
summary: Получить документ по ID
|
||
description: Получить информацию о документе
|
||
tags: [documents]
|
||
parameters:
|
||
- name: document_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: Информация о документе
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/DocumentResponse'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
put:
|
||
summary: Обновить документ
|
||
description: Обновить информацию о документе
|
||
tags: [documents]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: document_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/DocumentUpdate'
|
||
responses:
|
||
'200':
|
||
description: Документ обновлен
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/DocumentResponse'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
delete:
|
||
summary: Удалить документ
|
||
description: Удалить документ (только владелец коллекции)
|
||
tags: [documents]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: document_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'204':
|
||
description: Документ удален
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/documents/collection/{collection_id}:
|
||
get:
|
||
summary: Получить документы коллекции
|
||
description: Получить список документов в коллекции
|
||
tags: [documents]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: collection_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: skip
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 0
|
||
minimum: 0
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 100
|
||
minimum: 1
|
||
maximum: 1000
|
||
responses:
|
||
'200':
|
||
description: Список документов
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/DocumentResponse'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
|
||
/api/v1/conversations:
|
||
post:
|
||
summary: Создать беседу
|
||
description: Создать новую беседу для коллекции
|
||
tags: [conversations]
|
||
security:
|
||
- TelegramAuth: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConversationCreate'
|
||
responses:
|
||
'201':
|
||
description: Беседа создана
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConversationResponse'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
|
||
get:
|
||
summary: Получить список бесед
|
||
description: Получить список бесед текущего пользователя
|
||
tags: [conversations]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: skip
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 0
|
||
minimum: 0
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 100
|
||
minimum: 1
|
||
maximum: 1000
|
||
responses:
|
||
'200':
|
||
description: Список бесед
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConversationResponse'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
|
||
/api/v1/conversations/{conversation_id}:
|
||
get:
|
||
summary: Получить беседу по ID
|
||
description: Получить информацию о беседе
|
||
tags: [conversations]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: conversation_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: Информация о беседе
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConversationResponse'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
delete:
|
||
summary: Удалить беседу
|
||
description: Удалить беседу (только владелец)
|
||
tags: [conversations]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: conversation_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'204':
|
||
description: Беседа удалена
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/messages:
|
||
post:
|
||
summary: Создать сообщение
|
||
description: Создать новое сообщение в беседе
|
||
tags: [messages]
|
||
security:
|
||
- TelegramAuth: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MessageCreate'
|
||
responses:
|
||
'201':
|
||
description: Сообщение создано
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MessageResponse'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
|
||
/api/v1/messages/{message_id}:
|
||
get:
|
||
summary: Получить сообщение по ID
|
||
description: Получить информацию о сообщении
|
||
tags: [messages]
|
||
parameters:
|
||
- name: message_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: Информация о сообщении
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MessageResponse'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
put:
|
||
summary: Обновить сообщение
|
||
description: Обновить содержимое сообщения
|
||
tags: [messages]
|
||
parameters:
|
||
- name: message_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MessageUpdate'
|
||
responses:
|
||
'200':
|
||
description: Сообщение обновлено
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MessageResponse'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
delete:
|
||
summary: Удалить сообщение
|
||
description: Удалить сообщение
|
||
tags: [messages]
|
||
parameters:
|
||
- name: message_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'204':
|
||
description: Сообщение удалено
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/messages/conversation/{conversation_id}:
|
||
get:
|
||
summary: Получить сообщения беседы
|
||
description: Получить список сообщений в беседе
|
||
tags: [messages]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: conversation_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: skip
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 0
|
||
minimum: 0
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 100
|
||
minimum: 1
|
||
maximum: 1000
|
||
responses:
|
||
'200':
|
||
description: Список сообщений
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MessageResponse'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
|
||
/api/v1/rag/question:
|
||
post:
|
||
summary: Задать вопрос через RAG
|
||
description: Получить ответ на вопрос используя RAG (Retrieval-Augmented Generation)
|
||
tags: [rag]
|
||
security:
|
||
- TelegramAuth: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/QuestionRequest'
|
||
responses:
|
||
'200':
|
||
description: Ответ сгенерирован
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/RAGAnswer'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
|
||
/api/v1/admin/users:
|
||
get:
|
||
summary: Получить список всех пользователей (админ)
|
||
description: Получить список всех пользователей в системе (только для администраторов)
|
||
tags: [admin]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: skip
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 0
|
||
minimum: 0
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 100
|
||
minimum: 1
|
||
maximum: 1000
|
||
responses:
|
||
'200':
|
||
description: Список пользователей
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/UserResponse'
|
||
'403':
|
||
description: Требуются права администратора
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Error'
|
||
|
||
/api/v1/admin/collections:
|
||
get:
|
||
summary: Получить список всех коллекций (админ)
|
||
description: Получить список всех коллекций в системе (только для администраторов)
|
||
tags: [admin]
|
||
security:
|
||
- TelegramAuth: []
|
||
parameters:
|
||
- name: skip
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 0
|
||
minimum: 0
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 100
|
||
minimum: 1
|
||
maximum: 1000
|
||
responses:
|
||
'200':
|
||
description: Список коллекций
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/CollectionResponse'
|
||
'403':
|
||
description: Требуются права администратора
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Error'
|
||
|
||
components:
|
||
securitySchemes:
|
||
TelegramAuth:
|
||
type: apiKey
|
||
in: header
|
||
name: X-Telegram-ID
|
||
description: Telegram ID пользователя для аутентификации
|
||
|
||
schemas:
|
||
UserRole:
|
||
type: string
|
||
enum: [user, admin]
|
||
description: Роль пользователя
|
||
|
||
UserCreate:
|
||
type: object
|
||
required:
|
||
- telegram_id
|
||
- role
|
||
properties:
|
||
telegram_id:
|
||
type: string
|
||
description: Telegram ID пользователя
|
||
example: "123456789"
|
||
role:
|
||
$ref: '#/components/schemas/UserRole'
|
||
|
||
UserUpdate:
|
||
type: object
|
||
properties:
|
||
telegram_id:
|
||
type: string
|
||
description: Telegram ID пользователя
|
||
role:
|
||
$ref: '#/components/schemas/UserRole'
|
||
|
||
UserResponse:
|
||
type: object
|
||
properties:
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||
telegram_id:
|
||
type: string
|
||
example: "123456789"
|
||
role:
|
||
$ref: '#/components/schemas/UserRole'
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
example: "2024-01-01T00:00:00Z"
|
||
is_premium:
|
||
type: boolean
|
||
default: false
|
||
description: Является ли пользователь premium
|
||
premium_until:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
description: Дата окончания premium подписки
|
||
questions_used:
|
||
type: integer
|
||
default: 0
|
||
description: Количество использованных вопросов
|
||
|
||
CollectionCreate:
|
||
type: object
|
||
required:
|
||
- name
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Название коллекции
|
||
example: "Юридические документы"
|
||
description:
|
||
type: string
|
||
default: ""
|
||
description: Описание коллекции
|
||
example: "Коллекция юридических документов"
|
||
is_public:
|
||
type: boolean
|
||
default: false
|
||
description: Публичная ли коллекция
|
||
|
||
CollectionUpdate:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Название коллекции
|
||
description:
|
||
type: string
|
||
description: Описание коллекции
|
||
is_public:
|
||
type: boolean
|
||
description: Публичная ли коллекция
|
||
|
||
CollectionResponse:
|
||
type: object
|
||
properties:
|
||
collection_id:
|
||
type: string
|
||
format: uuid
|
||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||
name:
|
||
type: string
|
||
example: "Юридические документы"
|
||
description:
|
||
type: string
|
||
example: "Коллекция юридических документов"
|
||
owner_id:
|
||
type: string
|
||
format: uuid
|
||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||
is_public:
|
||
type: boolean
|
||
example: false
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
example: "2024-01-01T00:00:00Z"
|
||
|
||
CollectionAccessGrant:
|
||
type: object
|
||
required:
|
||
- user_id
|
||
properties:
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
description: ID пользователя для предоставления доступа
|
||
|
||
CollectionAccessResponse:
|
||
type: object
|
||
properties:
|
||
access_id:
|
||
type: string
|
||
format: uuid
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
collection_id:
|
||
type: string
|
||
format: uuid
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
|
||
CollectionAccessUserInfo:
|
||
type: object
|
||
properties:
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
telegram_id:
|
||
type: string
|
||
role:
|
||
type: string
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
|
||
CollectionAccessListResponse:
|
||
type: object
|
||
properties:
|
||
access_id:
|
||
type: string
|
||
format: uuid
|
||
user:
|
||
$ref: '#/components/schemas/CollectionAccessUserInfo'
|
||
collection_id:
|
||
type: string
|
||
format: uuid
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
|
||
DocumentCreate:
|
||
type: object
|
||
required:
|
||
- collection_id
|
||
- title
|
||
- content
|
||
properties:
|
||
collection_id:
|
||
type: string
|
||
format: uuid
|
||
description: ID коллекции
|
||
title:
|
||
type: string
|
||
description: Название документа
|
||
example: "Гражданский кодекс РФ"
|
||
content:
|
||
type: string
|
||
description: Содержимое документа
|
||
example: "Статья 1. Гражданское законодательство..."
|
||
metadata:
|
||
type: object
|
||
additionalProperties: true
|
||
default: {}
|
||
description: Дополнительные метаданные
|
||
|
||
DocumentUpdate:
|
||
type: object
|
||
properties:
|
||
title:
|
||
type: string
|
||
description: Название документа
|
||
content:
|
||
type: string
|
||
description: Содержимое документа
|
||
metadata:
|
||
type: object
|
||
additionalProperties: true
|
||
description: Дополнительные метаданные
|
||
|
||
DocumentResponse:
|
||
type: object
|
||
properties:
|
||
document_id:
|
||
type: string
|
||
format: uuid
|
||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||
collection_id:
|
||
type: string
|
||
format: uuid
|
||
title:
|
||
type: string
|
||
example: "Гражданский кодекс РФ"
|
||
content:
|
||
type: string
|
||
example: "Статья 1. Гражданское законодательство..."
|
||
metadata:
|
||
type: object
|
||
additionalProperties: true
|
||
example:
|
||
filename: "document.pdf"
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
example: "2024-01-01T00:00:00Z"
|
||
|
||
ConversationCreate:
|
||
type: object
|
||
required:
|
||
- collection_id
|
||
properties:
|
||
collection_id:
|
||
type: string
|
||
format: uuid
|
||
description: ID коллекции для беседы
|
||
|
||
ConversationResponse:
|
||
type: object
|
||
properties:
|
||
conversation_id:
|
||
type: string
|
||
format: uuid
|
||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
collection_id:
|
||
type: string
|
||
format: uuid
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
example: "2024-01-01T00:00:00Z"
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
example: "2024-01-01T00:00:00Z"
|
||
|
||
MessageRole:
|
||
type: string
|
||
enum: [user, assistant, system]
|
||
description: Роль сообщения
|
||
|
||
MessageCreate:
|
||
type: object
|
||
required:
|
||
- conversation_id
|
||
- content
|
||
- role
|
||
properties:
|
||
conversation_id:
|
||
type: string
|
||
format: uuid
|
||
description: ID беседы
|
||
content:
|
||
type: string
|
||
description: Содержимое сообщения
|
||
example: "Какие права имеет работник?"
|
||
role:
|
||
$ref: '#/components/schemas/MessageRole'
|
||
sources:
|
||
type: object
|
||
additionalProperties: true
|
||
default: {}
|
||
description: Источники для сообщения
|
||
|
||
MessageUpdate:
|
||
type: object
|
||
properties:
|
||
content:
|
||
type: string
|
||
description: Содержимое сообщения
|
||
sources:
|
||
type: object
|
||
additionalProperties: true
|
||
description: Источники для сообщения
|
||
|
||
MessageResponse:
|
||
type: object
|
||
properties:
|
||
message_id:
|
||
type: string
|
||
format: uuid
|
||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||
conversation_id:
|
||
type: string
|
||
format: uuid
|
||
content:
|
||
type: string
|
||
example: "Работник имеет следующие права..."
|
||
role:
|
||
$ref: '#/components/schemas/MessageRole'
|
||
sources:
|
||
type: object
|
||
additionalProperties: true
|
||
example:
|
||
chunks:
|
||
- document_id: "123e4567-e89b-12d3-a456-426614174000"
|
||
chunk_id: "456e7890-e12b-34c5-d678-901234567890"
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
example: "2024-01-01T00:00:00Z"
|
||
|
||
QuestionRequest:
|
||
type: object
|
||
required:
|
||
- conversation_id
|
||
- question
|
||
properties:
|
||
conversation_id:
|
||
type: string
|
||
format: uuid
|
||
description: ID беседы
|
||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||
question:
|
||
type: string
|
||
minLength: 3
|
||
description: Вопрос пользователя
|
||
example: "Какие права имеет работник при увольнении?"
|
||
top_k:
|
||
type: integer
|
||
default: 20
|
||
minimum: 1
|
||
maximum: 100
|
||
description: Количество кандидатов для векторного поиска
|
||
rerank_top_n:
|
||
type: integer
|
||
default: 5
|
||
minimum: 1
|
||
maximum: 20
|
||
description: Количество релевантных чанков после реранкинга
|
||
|
||
RAGSource:
|
||
type: object
|
||
properties:
|
||
index:
|
||
type: integer
|
||
description: Порядковый номер источника
|
||
example: 1
|
||
document_id:
|
||
type: string
|
||
format: uuid
|
||
description: ID документа
|
||
example: "123e4567-e89b-12d3-a456-426614174000"
|
||
chunk_id:
|
||
type: string
|
||
format: uuid
|
||
description: ID чанка
|
||
example: "456e7890-e12b-34c5-d678-901234567890"
|
||
title:
|
||
type: string
|
||
nullable: true
|
||
description: Название документа
|
||
example: "Трудовой кодекс РФ"
|
||
|
||
RAGAnswer:
|
||
type: object
|
||
properties:
|
||
answer:
|
||
type: string
|
||
description: Сгенерированный ответ на вопрос
|
||
example: "Работник при увольнении имеет право на..."
|
||
sources:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/RAGSource'
|
||
description: Список источников, использованных для генерации ответа
|
||
usage:
|
||
type: object
|
||
additionalProperties: true
|
||
description: Информация об использовании токенов
|
||
example:
|
||
prompt_tokens: 150
|
||
completion_tokens: 250
|
||
total_tokens: 400
|
||
|
||
Error:
|
||
type: object
|
||
properties:
|
||
detail:
|
||
type: string
|
||
description: Описание ошибки
|
||
example: "Ресурс не найден"
|
||
|
||
responses:
|
||
BadRequest:
|
||
description: Неверный запрос
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Error'
|
||
example:
|
||
detail: "Неверные параметры запроса"
|
||
|
||
Unauthorized:
|
||
description: Не авторизован
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Error'
|
||
example:
|
||
detail: "Требуется аутентификация"
|
||
|
||
Forbidden:
|
||
description: Доступ запрещен
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Error'
|
||
example:
|
||
detail: "У вас нет доступа к этому ресурсу"
|
||
|
||
NotFound:
|
||
description: Ресурс не найден
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Error'
|
||
example:
|
||
detail: "Ресурс не найден"
|
||
|
||
InternalServerError:
|
||
description: Внутренняя ошибка сервера
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Error'
|
||
example:
|
||
detail: "Внутренняя ошибка сервера" |