Спецификация OpenAPI

Система SOBERIS автоматически генерирует документацию API в формате OpenAPI 3.0 для каждой созданной схемы, обеспечивая полную интеграционную готовность с интерактивной документацией и возможностью тестирования эндпоинтов непосредственно из браузера.
Автоматическая генерация
  • Создание спецификации на основе схем
  • Валидация структуры данных
  • Актуальная документация API
  • Соответствие стандарту OpenAPI 3.0
Интерактивность
  • Тестирование API из браузера
  • Swagger UI интерфейс
  • Примеры запросов и ответов
  • Поддержка аутентификации
Доступ к спецификации OpenAPI

Спецификация OpenAPI доступна в интерфейсе приложения по адресу /specification/{schemaName}, где schemaName - это название схемы документа или справочника.
🔗 Навигация к спецификации
  • Через главное меню: раздел "Спецификация"
  • Прямой доступ по URL: /specification/{schemaName}
  • Из списка схем: кнопка "Спецификация" для конкретной схемы
Функциональность спецификации

Интерфейс Swagger UI

Спецификация отображается с помощью Swagger UI, предоставляя интерактивный интерфейс для:
Просмотр API
  • Список всех доступных эндпоинтов
  • Детальное описание каждого метода
  • Структура запросов и ответов
  • Примеры использования
Тестирование API
  • Выполнение запросов из браузера
  • Ввод параметров и данных
  • Просмотр ответов сервера
  • Проверка статус-кодов
Доступные API операции

Система генерирует следующие группы эндпоинтов для каждой схемы:
Работа с аутентификацией

API-ключи

Для работы с API требуется API-ключ, который необходимо указать в заголовке SBRS-API-Key.
🔑 Настройка аутентификации в Swagger UI
1. Нажмите кнопку "Authorize" в верхней части интерфейса
2. В поле "ApiKeyAuth" введите ваш API-ключ
3. Нажмите "Authorize" для сохранения
4. Теперь все запросы будут автоматически включать API-ключ
Обязательные заголовки

Каждый запрос к API должен содержать набор обязательных заголовков для корректной работы системы:
* Обязателен для операций с данными
** Опциональный, но рекомендуется для атомарных операций
Структура запросов и ответов

Пример запроса INSERT

Добавление нового документа в коллекцию:
POST /sbrs-data/insert-one
{
"name": "Новый пользователь",
"email": "user@example.com",
"age": 30,
"department": "IT"
}
Пример ответа
Успешный ответ (200 OK)
{
"documentId": "507f1f77bcf86cd799439011",
"sbrsMessageType": "success",
"sbrsStatusMessage": "Документ успешно добавлен"
}
Пример запроса UPDATE
POST /sbrs-data/update-one
{
    "filter": {
        "_id": "507f1f77bcf86cd799439011"
    },
    "update": {
        "$set": {
            "age": 31,
            "department": "Engineering"
        }
    }
}
Пример запроса SEARCH
POST /sbrs-data/search
{
    "filter": {
        "department": "IT",
        "age": {
            "$gte": 25
        }
    },
    "sort": {
        "name": 1,
        "_createdAt": -1
    }
}
Коды ошибок

API возвращает стандартные HTTP-коды состояния и специфичные для системы коды ошибок:
Скачивание спецификации

Интерфейс предоставляет возможность скачать полную спецификацию OpenAPI в формате JSON:
💾 Экспорт спецификации
  • Нажмите кнопку "Скачать спецификацию" в правом верхнем углу
  • Файл будет содержать полную спецификацию OpenAPI 3.0.3
  • Можно использовать для генерации клиентских SDK
  • Совместим с инструментами разработки API
Практические рекомендации
💡 Советы по использованию
  • Всегда используйте транзакции для группировки связанных операций
  • Проверяйте схему перед отправкой данных через эндпоинт insert-one
  • Используйте фильтрацию в запросах search для оптимизации производительности
  • Мониторьте коды ошибок для диагностики проблем интеграции
  • Сохраняйте API-ключи в безопасном месте и регулярно обновляйте их
  • Используйте correlation ID для отслеживания запросов в логах
⚠️ Важные замечания
  • Операция delete-one выполняет мягкое удаление (soft delete)
  • Все временные метки используют формат ISO 8601
  • Максимальный размер запроса ограничен настройками сервера
  • API поддерживает только JSON формат данных
Интеграция с внешними системами

Спецификация OpenAPI может использоваться для автоматической генерации клиентских библиотек и интеграции с внешними системами:
# Пример интеграции с curl
curl -X POST "http://localhost:8588/sbrs-data/insert-one" \
-H "Content-Type: application/json" \
-H "SBRS-API-Key: your-api-key" \
-H "SBRS-Correlation-Id: $(uuidgen)" \
-H "SBRS-Originator: external-system" \
-H "SBRS-Message-Id: $(uuidgen)" \
-H "SBRS-Schema-Name: user-schema" \
-d '{
"name": "John Doe",
"email": "john@example.com"
}'