Войти

Справочник OpenAPI

Stable

Как использовать OpenAPI как контракт для схем запросов и ответов Control Plane API.

Обновлено: 5 марта 2026 г.

OpenAPI — это машиночитаемый контракт Control Plane API: по нему удобно проверять схемы запросов и ответов, генерировать клиентов и импортировать коллекции в инструменты вроде Postman или Insomnia.

Когда OpenAPI полезен

OpenAPI особенно нужен в трёх случаях:

  • вы пишете собственную интеграцию и хотите валидировать payload заранее;
  • вы генерируете типы или SDK для внутреннего сервиса;
  • вы собираете тестовую коллекцию запросов и не хотите вручную переносить схемы.

Что важно помнить

  • пользовательский API находится под префиксом /v2;
  • для авторизации используется Authorization: Bearer <api-key>;
  • PostgreSQL‑DSN и tenant credentials в OpenAPI не заменяют обычное подключение через Gateway;
  • наличие интерактивной reference‑страницы зависит от конкретного контура поставки.

Как использовать спецификацию на практике

  1. Получите опубликованную OpenAPI‑спецификацию вашего контура.
  2. Импортируйте её в Postman, Insomnia или генератор клиента.
  3. Проверьте, что base URL указывает на ваш Control Plane.
  4. Добавьте Bearer‑авторизацию и окружение с CP_URL.
  5. Для рабочих сценариев рядом держите curl‑примеры из документации — они проще для отладки вручную.

Если интерактивная reference недоступна

Это не мешает повседневной работе. Для большинства пользователей достаточно:

  • описания API‑маршрутов в разделе API;
  • готовых curl‑примеров;
  • Console для ручных операций;
  • CLI для терминального сценария.

OpenAPI здесь скорее инструмент точной интеграции, чем обязательная ежедневная точка входа.

Почему SPG99АрхитектураПлан развитияДокументацияБлог