Расширение «HTTPСервисы» для OpenAPI 3.0

Благодарность. Подсистема разработана Александром Янгом и опубликована в репозитории alexandr-yang/http-services. Текущий репозиторий — бывший форк этой работы; спасибо автору за исходную реализацию и открытую лицензию (MPL 2.0).

Расширение конфигурации 1С, которое добавляет подсистему для описания HTTP-сервисов по схемам OpenAPI 3.0 и единообразной обработки входящих запросов: валидация по контракту, цепочка обработчиков, формирование ответа.

Назначение

Расширение решает две связанные задачи:

1. Хранение и просмотр контрактов — схема OpenAPI (JSON) загружается в справочник, преобразуется во внутреннее представление 1С и отображается в удобном виде (параметры, тело запроса, ответы).
2. Исполнение HTTP-сервисов — из обработчика платформенного HTTP-сервиса вызывается единая точка входа HTTPСервисЗапросы.ОбработатьЗапрос(), которая проходит фиксированный конвейер этапов и возвращает готовый HTTPСервисОтвет.

Подключение к конкретной конфигурации выполняется как расширение; бизнес-логика конкретных эндпоинтов регистрируется в переопределяемом модуле HTTPСервисЗапросыПереопределяемый.

Типовой сценарий внедрения

1. Подключить расширение HTTPСервисы к информационной базе.
2. Назначить роли ЧтениеHTTPСервисов / ИзменениеHTTPСервисов.
3. Загрузить OpenAPI-схему в Схемы HTTP-сервисов.
4. Создать элемент HTTP-сервисы с нужным operationId.
5. В конфигурации создать платформенный HTTP-сервис и в каждом URL-шаблоне вызвать HTTPСервисЗапросы.ОбработатьЗапрос().
6. В HTTPСервисЗапросыПереопределяемый зарегистрировать обработчики для ссылок из справочника.

---

Работа со схемами OpenAPI

1. Создайте элемент Справочник.СхемыHTTPСервисов и вставьте текст схемы OpenAPI 3.0.x в реквизит Схема JSON.
2. При записи схема парсится модулем СхемыHTTPСервисов и сохраняется в Схема 1С (ХранилищеЗначения, сжатие).
3. На форме элемента схемы отображаются операции, параметры, тело запроса и варианты ответов.
4. Создайте элемент Справочник.HTTPСервисы: укажите схему, выберите Идентификатор (operationId) из списка, установите Включен.

Поддерживаются версии OpenAPI 3.0.3 и 3.0.4 (см. СхемыHTTPСервисовПовтИсп).

Валидация охватывает:

• параметры path, query, header, cookie;
• тело запроса (JSON, строка, двоичные данные);
• заголовки и тело ответа для соответствующего кода состояния.

---

Регистрация обработчиков

В общем модуле HTTPСервисЗапросыПереопределяемый реализуются процедуры:

Процедура	Назначение
ПриДобавленииОбработчиковЗапросов	Бизнес-логика эндпоинта
ПриДобавленииОбработчиковПроверкиЗапросов	Дополнительная проверка запроса
ПриДобавленииОбработчиковПроверкиОтветов	Дополнительная проверка ответа
ПриДобавленииОбработчиковПроверкиПравДоступа	Авторизация / проверка прав

Каждая строка таблицы обработчиков содержит:

Колонка	Описание
HTTPСервис	Ссылка на элемент Справочник.HTTPСервисы
Обработчик	Имя экспортной процедуры, например МойМодуль.ОбработатьЗапросDemo
ВПривилегированномРежиме	Выполнять в привилегированном режиме
ВТранзакции	Оборачивать в транзакцию

Зависимости и ограничения

• Версия платформы 8.3.23 и выше
• Поддерживается стандарт OAS 3.0.3/4
• Все HTTP‑сервисы должны содержать свойство operationId
• Типы integer и number интерпретируются как Число
• При чтении схемы не поддерживаются конструкции allOf, not, style, explode, allowEmptyValue, allowReserved
• Не поддерживается валидация параметров с источником cookie
• Для ответов не поддерживается вариант default
• Нет поддержки XML

---

Лицензия

Исходный код распространяется на условиях Mozilla Public License 2.0 (см. файл LICENSE в корне репозитория).