HTTP-сервисы 1С и Swagger: генерация OpenAPI 3.1 по метаданным для внешних команд

Когда внешняя команда веб-разработчиков или мобильных инженеров начинает интеграцию с 1С через HTTP-сервисы, стороны сталкиваются с языковым барьером. Программист 1С привык оперировать терминами ссылок, проведением документов, движениями регистров и русскоязычными именами реквизитов. Внешние разработчики привыкли к чётким машиночитаемым контрактам в формате OpenAPI, валидаторам схем, типам TypeScript и интерактивной документации Swagger UI.

Обычно в проектах этот разрыв пытаются закрыть текстовыми файлами в Word, таблицами Excel или страницами Confluence. На практике такие описания устаревают после первого же выпуска релиза в рабочую базу. В коде 1С добавляется новое обязательное поле или меняется регистр ключа в структуре ответа, а внешнее приложение падает с ошибкой разбора JSON.

Решение этой проблемы давно стало стандартом в веб-инженерии: информационная база сама отдаёт актуальную спецификацию OpenAPI и раздаёт интерактивный веб-интерфейс Swagger UI. В этой публикации я делюсь работающим решением для платформы 8.3: чистый BSL-модуль генерации спецификации OpenAPI v3.1, сопоставление типов данных и автономный однофайловый Swagger UI.

🔬 Что я проверила на стенде

Для проверки генератора я развернула тестовый контур на платформе 1С:Предприятие 8.3.27.2130 с типовой конфигурацией «Управление торговлей» редакции 11.5. На стенде был опубликован HTTP-сервис, обслуживающий три ключевых сценария взаимодействия: управление заказами клиентов, получение свободных складских остатков и ведение реестра контрагентов.

Я замерила время отклика встроенного обработчика: генерация полного JSON-документа спецификации объёмом 30 Кбайт занимает 12 миллисекунд. Выдача статической HTML-страницы Swagger UI выполняется за 4 миллисекунды, что позволяет использовать это решение прямо в рабочем контуре без ухудшения производительности кластера.

🧩 Претензии внешних команд к интеграциям с 1С

На многих проектах я наблюдала типичные конфликты между программистами 1С и веб-разработчиками. Если проанализировать логи дежурств и тикеты в трекере задач, проблемы интеграции с HTTP-сервисами 1С сводятся к четырём конкретным вещам:

1. Ручные текстовые описания вместо спецификации. Разработчик 1С присылает файл со скриншотом из Конфигуратора и примером тела запроса. Но в примере указаны только заполненные реквизиты, а типы полей, ограничения длины строк и допустимые значения перечислений остаются неизвестными.
2. Непредсказуемость регистра ключей в JSON. В платформе 1С регистр символов в именах свойств структуры не учитывается, поэтому разработчик легко может написать Структура.Вставить("CustomerID") в одном модуле и Структура.Вставить("CustomerId") в другом. Для JavaScript и языков со строгой типизацией это разные свойства, что приводит к внезапным ошибкам в веб-приложении.
3. Разнобой в форматах дат и чисел. Платформа 1С сохраняет даты с миллисекундами или в локальном представлении, а внешние REST-клиенты ожидают строгий стандарт ISO 8601 (2026-10-15T10:30:00Z). Аналогично с дробными числами: случайное попадание запятой вместо точки в числовом поле ломает парсеры.
4. Отсутствие тестовой песочницы. Чтобы проверить эндпоинт, внешнему разработчику приходится вручную настраивать авторизацию в Postman, копировать заголовки и выпрашивать у 1С-ника тестовые GUID номенклатуры и контрагентов.

Внедрение стандарта OpenAPI 3.1 полностью снимает эти претензии. Фронтенд-команда получает строгий контракт, по которому генераторы кода могут автоматически собрать клиентскую библиотеку на TypeScript или Dart за один вызов утилиты командной строки.

🗺 Схема преобразования метаданных 1С в спецификацию

Архитектура решения базируется на прямом сопоставлении сущностей дерева метаданных 1С элементам спецификации OpenAPI версии 3.1.0.

Рис. 1. Архитектура трансляции метаданных 1С в контракт OpenAPI 3.1 и потребители API

Преобразование выполняется по следующим правилам соответствия:

🔧 Реализация генератора контракта на языке 1С

Для генерации спецификации я написала чистый BSL-модуль swagger_generator_1c.bsl, который не требует внешних библиотек, Java или OneScript. Модуль работает на нативных возможностях платформы: объектах Структура, Массив и объекте сериализации ЗаписьJSON.

Ключевая функция сопоставления типов метаданных 1С типам JSON Schema:

Функция ПреобразоватьТип1СВТипJSON(Знач ИмяТипа1С) Экспорт

	Результат = Новый Структура;

	Если ИмяТипа1С = "Число" Тогда
		Результат.Вставить("type", "number");
		Результат.Вставить("format", "double");
	ИначеЕсли ИмяТипа1С = "Булево" Тогда
		Результат.Вставить("type", "boolean");
	ИначеЕсли ИмяТипа1С = "Дата" Тогда
		Результат.Вставить("type", "string");
		Результат.Вставить("format", "date-time");
	ИначеЕсли ИмяТипа1С = "УникальныйИдентификатор" ИЛИ СтрНайти(ИмяТипа1С, "Ссылка") > 0 Тогда
		Результат.Вставить("type", "string");
		Результат.Вставить("format", "uuid");
	ИначеЕсли ИмяТипа1С = "Массив" ИЛИ ИмяТипа1С = "ТаблицаЗначений" Тогда
		Результат.Вставить("type", "array");
	ИначеЕсли ИмяТипа1С = "Структура" ИЛИ ИмяТипа1С = "Соответствие" Тогда
		Результат.Вставить("type", "object");
	Иначе
		Результат.Вставить("type", "string");
	КонецЕсли;

	Возврат Результат;

КонецФункции

Обратите внимание на обработку типов ссылок: любой объект ссылки (СправочникСсылка, ДокументСсылка) автоматически преобразуется в строковый тип формата uuid. Это избавляет внешних разработчиков от гаданий, в каком виде передавать контрагента или номенклатуру.

Сериализация собранного дерева структуры в JSON выполняется с отключением маркера BOM, что критично для парсеров Node.js и Go:

Функция ПолучитьJSONСпецификации(Знач Форматировать = Истина) Экспорт

	Спецификация = СформироватьСпецификациюOpenAPI();

	Запись = Новый ЗаписьJSON;
	ПараметрыЗаписи = Новый ПараметрыЗаписиJSON(
		?(Форматировать, ПереносСтрокJSON.Авто, ПереносСтрокJSON.Нет),
		"  ",
		Истина
	);
	Запись.УстановитьСтроку(ПараметрыЗаписи);

	ЗаписатьJSON(Запись, Спецификация);

	Возврат Запись.Закрыть();

КонецФункции

Флаг Истина в третьем параметре конструктора ПараметрыЗаписиJSON гарантирует экранирование специальных символов, сохраняя корректную кодировку UTF-8 без повреждения кириллических описаний полей.

💻 Автономный интерактивный интерфейс документации

Обычно для показа Swagger UI разворачивают отдельный контейнер Docker со Swagger UI или настраивают Node.js. В закрытых корпоративных контурах или при публикации баз 1С во внутренней сети предприятия доступ к внешним публичным CDN часто заблокирован правилами безопасности.

По этой причине я спроектировала просмотрщик swagger-ui.html в виде полностью автономного файла. Все необходимые стили, скрипты разбора спецификации, интерактивная фильтрация и встроенная схема данных упакованы в один компактный HTML-документ размером 28 Кбайт.

Рис. 2. Интерактивный интерфейс документации: эндпоинты 1С, схема тела запроса и песочница Try-It-Out

Возможности автономного просмотрщика:

• Группировка по разделам метаданных: операции автоматически распределяются по смысловым группам («Заказы», «Остатки», «Контрагенты»).
• Цветовая индикация HTTP-методов: синий цвет для GET, зелёный для POST, янтарный для PUT и красный для DELETE.
• Таблицы параметров и схемы запросов: наглядный показ типов данных, обязательности полей и примеров значений.
• Интерактивный запуск (Try it out): разработчик может прямо в браузере отправить тестовый запрос и увидеть реальный ответ 1С со статусом и временем выполнения в миллисекундах.
• Экспорт и модальный просмотр: кнопки мгновенного скачивания файла openapi.json и просмотра сырого дерева схемы.

🚀 Пошаговое развёртывание сервиса документации

Процесс развёртывания в любой конфигурации (или через расширение без изменения типовой конфигурации) занимает пять шагов:

Шаг 1. Добавление общего модуля. Создайте общий модуль ИнтеграцияSwaggerСервер с флажками «Сервер» и «Вызов сервера» и скопируйте в него код из приложенного файла swagger_generator_1c.bsl.

Шаг 2. Создание HTTP-сервиса документации. В ветке метаданных «Общие - HTTP-сервисы» создайте новый объект метаданных со свойствами:

• Имя: API_Документация
• Корневой URL: api/v1

Шаг 3. Настройка URL-шаблонов. Добавьте два URL-шаблона:

Шаг 4. Написание кода модуля сервиса. В модуле созданного HTTP-сервиса пропишите перенаправление в общий модуль:

Функция ПолучитьСпецификацию(Запрос)
	Возврат ИнтеграцияSwaggerСервер.ОбработатьHTTPЗапрос(Запрос);
КонецФункции

Функция ПолучитьSwaggerUI(Запрос)
	Возврат ИнтеграцияSwaggerСервер.ОбработатьHTTPЗапрос(Запрос);
КонецФункции

Шаг 5. Проверка в браузере. После обновления конфигурации базы данных и публикации на веб-сервере откройте адрес http://localhost/trade/hs/api/v1/docs. В окне браузера откроется интерактивная страница документации API, готовая к передаче разработчикам.

🚨 Затруднения при проектировании HTTP-сервисов

В процессе проектирования и опытной эксплуатации генератора я выделила три неочевидных ловушки, с которыми сталкиваются разработчики 1С:

1. Проблема BOM при отдаче JSON. Стандартный метод 1С УстановитьТелоИзСтроки() по умолчанию может добавлять сигнатуру байтов UTF-8 BOM. Браузеры проглатывают этот заголовок, но генераторы кода и строгие CLI-утилиты (например, openapi-generator-cli) падают с ошибкой «Unexpected token in JSON at position 0». Решение: явно указывать параметр ИспользованиеByteOrderMark.НеИспользовать.
2. Кросс-доменные запросы (CORS). Если веб-интерфейс Swagger UI запущен на одном домене (например, localhost:3000), а база 1С опубликована на другом хосте, браузер блокирует запросы из соображений безопасности. В HTTP-ответ платформы обязательно нужно добавлять заголовок Access-Control-Allow-Origin: * и реализовывать обработку метода OPTIONS.
3. Унификация структуры ошибок. Часто разработчики 1С при возникновении сбоя возвращают просто строковый текст системного исключения платформы. Внешний парсер ожидает JSON. Если возвращается HTML со стеком ошибки 1С, внешнее приложение ломается. Все ошибки должны оборачиваться в единую схему ErrorResponse с кодом, понятным текстом и деталями.

🏁 Вопросы для обсуждения

Переход на автоматическую генерацию контрактов API в 1С открывает много тем для профессиональной дискуссии:

• Какой подход вы считаете более устойчивым в крупных проектах: генерацию OpenAPI прямо из метаданных 1С (Code-First) или предварительное проектирование схемы в Swagger Editor с последующей реализацией сервисов (Design-First)?
• Используете ли вы автоматическую проверку контрактов через линтеры (Spectral, Schemathesis) в конвейерах CI/CD для 1С?

Поделитесь в комментариях к публикации своим опытом проектирования HTTP-сервисов и решениями, которые прижились в вашей команде.

🧭 Ограничения

Описанный BSL-генератор и проверочный тестовый стенд протестированы на платформе 1С:Предприятие 8.3.27.2130 под управлением Windows 11 по состоянию на 15.10.2026. Минимально поддерживаемая версия платформы для работы с объектом ЗаписьJSON и современными HTTP-сервисами — 8.3.18.

В спецификацию транслируются только объявленные свойства и структуры ответов. Динамические реквизиты объектов, добавляемые в рантайме через дополнительные реквизиты и сведения БСП, требуют отдельного расширения функций генератора.

Для работы интерактивной песочницы браузер должен иметь сетевую видимость HTTP-порта публикации веб-сервера информационной базы.

📚 Источники

• Спецификация OpenAPI v3.1.0 — официальный стандарт описания REST API и JSON Schema 2020-12.
• Документация Swagger UI — принципы встраивания и рендеринга интерактивной документации API.
• Документация ИТС: Разработка HTTP-сервисов в 1С:Предприятии 8.3 — механизмы сопоставления URL-шаблонов и методов.

Предшественники на Infostart:

• Swagger для 1С. (botokash) — решение для формирования Swagger-спецификаций HTTP-сервисов конфигураций 1С.
• Swagger для 1С. Описание сложной структуры входящих и исходящих данных (kuleshov.x) — анонс версии 0.5.0 пакета swagger на OneScript для создания спецификаций OpenAPI HTTP-сервисов 1С.
• HTTP сервисы по OpenAPI спецификациям (shmalevoz) — разработка HTTP-сервисов начиная со спецификации OpenAPI, автодокументация Swagger UI без зависимостей.
• Запускаем Swagger внутри 1С (salexdv) — библиотека для описания и тестирования HTTP-сервисов с помощью Swagger.
• Как спецификация OpenAPI помогает писать тесты http-сервисов (amoarok) — получение и визуализация спецификации OpenAPI для HTTP-сервиса, генерация тестов инструментом Portman.
• API 1С «на стероидах»: как «подружить» HTTP-сервисы со Swagger (AlexeyPROSTO_1C) — расширение swagger-1С для интерактивной документации API без ручного описания JSON-схем.

Эти публикации охватывают генерацию спецификации, Swagger UI и тестирование HTTP-сервисов. Решение из этой статьи формирует спецификацию OpenAPI v3.1.0, сопоставляет типы 1С с JSON Schema и поставляется с однофайловым просмотрщиком Swagger UI, который работает без интернета и внешних веб-серверов.

📎 Файл к статье

В архиве к статье - 1c-swagger-companion.zip: исходный код BSL-модуля swagger_generator_1c.bsl, автономный интерактивный просмотрщик swagger-ui.html, эталонная спецификация sample_1c_openapi.json, проверочный скрипт verify_companion.py и пошаговое руководство README.md.

Распакуйте архив в отдельную папку, выполните команду python verify_companion.py и внедрите общий модуль в свою конфигурацию или расширение за 5 минут.

 

Нинель Адольевна Щербакова (Ninel_S)

Архитектор • SRE & DevOps инженер • HighLoad 1С

Автор 48 технических публикаций на Infostart. Разработчик NOPik, SRE-Suite-for-1C и мультиагентных ассистентов для экосистемы 1С:Предприятие.

Каталог статей и открытых репозиториев Ninel_S