Swagger: справочник и сценарии

Где открыть Swagger и как читать описание endpoint'ов.

Swagger (в терминах OpenAPI 2.0) — источник истины по перечню операций Shturval Backend API, параметрам запроса, схемам ответов и коду ошибок. Пользовательская документация на сайте не копирует сотни путей: актуальность поддерживается через спецификацию (файл swagger.json в поставке backend, версия API в поле info.version, например 2.14.0, и базовый путь /api/v1).

Swagger в графическом интерфейсе

Интерактивная документация API доступна в графическом интерфейсе платформы:

  1. Перейдите в раздел О системе верхнего меню платформы.
  2. Нажмите кнопку Swagger для запуска документации.

В Swagger UI перечислены все paths, методы, параметры и примеры запросов, соответствующие текущему swagger.json.

Как читать security и permissions

  • Во многих операциях в блоке security фигурирует схема Bearer: в запросах к API укажите Authorization: Bearer <token> (см. Авторизация и токен).
  • Наличие токена не гарантирует успех вызова: проверяются права на конкретную операцию в контексте кластера/платформы.
  • Коды 401 / 403 в описании ответа означают типичные сценарии отсутствия аутентификации или недостаточных прав — сопоставляйте с настройками ролей в вашей организации.

Как не потеряться в списке тегов (tags)

В swagger.json много тегов, привязанных к группам операций (кластер, неймспейс, провайдер, observability и т.д.). Практичный путь:

  1. Определите префикс пути по структуре API (/clusters/..., /platform/..., /tenants/... или WebSocket).
  2. В Swagger UI воспользуйтесь поиском по спецификации.
  3. Откройте конкретный path и method — внизу смотрите Responses и пример тела.

Связанные страницы

← Структура API: пути и область
Что делать, если не хватает прав доступа? →