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

Ниже разберу оба варианта, публикацию на веб-сервере, CORS и ошибки, на которых спотыкаются при первом запуске.

Зачем API в 1С документация в OpenAPI

Знакомая переписка с интегратором: «Какой формат даты вы принимаете?», «Пришлите пример JSON», «А код склада строкой или числом?». Документ в Word устаревает после второго релиза, а скриншоты тестовой обработки ничего не объясняют.

OpenAPI решает это стандартным способом:

Что даётПочему это важно
Единый формат описанияИнтегратор читает API 1С так же, как любой REST API
Swagger UI и аналогиМетоды, параметры и примеры в браузере, кнопка «попробовать»
Генерация клиентовВнешняя команда генерирует клиентский код по спецификации
Описание рядом с кодомДокументация меняется вместе с сервисом, а не «потом»
Swagger для 1С: интерактивная документация HTTP-сервиса прямо из базы
Swagger для 1С: интерактивная документация HTTP-сервиса прямо из базы

Вариант 1: открытое расширение swagger-1c

На GitHub есть открытый проект swagger-1c (репозиторий zerobig/swagger-1c) — расширение конфигурации, которое:

  • находит описания ваших HTTP-сервисов в специальных общих модулях;
  • на лету формирует спецификацию OpenAPI;
  • отдаёт веб-интерфейс документации по адресу вида /hs/swagger/index.html;
  • умеет проверять входящие параметры и ответы на соответствие описанию.

Исполняемый код сервисов при этом не меняется: модуль-описание содержит только описания.

Установка

  1. Создайте в конфигураторе новое расширение и загрузите в него файл расширения из репозитория («Конфигурация» → «Загрузить конфигурацию из файла»).
  2. Обновите конфигурацию базы.
  3. Переопубликуйте базу на веб-сервере с флажком «Публиковать HTTP-сервисы расширений по умолчанию».
  4. Перезапустите веб-сервер.
  5. Откройте http://сервер/ИмяПубликации/hs/swagger/index.html.

Шаг 3 пропускают чаще всего: без флажка HTTP-сервисы расширений не публикуются, и по адресу документации будет 404.

Интерфейс документации можно выбрать параметром ui в адресе: кроме классического Swagger UI поддерживаются ReDoc, RapiDoc и другие. Если стандартный интерфейс не отрисовывается, попробуйте другой — например, ?ui=RapiDoc.

Модуль-описание сервиса

Расширение ищет описание в общем модуле, имя которого строится как <ИмяHTTPСервиса>Описание. Для сервиса ОстаткиСклада — модуль ОстаткиСкладаОписание. Состав экспортных функций модуля задан документацией проекта; описание методов строится цепочкой вызовов:

1С
// Описание методов HTTP-сервиса ОстаткиСклада для спецификации OpenAPI.
Функция ПолучитьОписаниеHTTPСервиса() Экспорт

	Методы = Swag_Описание
		.Метод("ОстаткиGET")
			.ОписаниеМетода("Остатки товаров на складе")
			.ПараметрЗапроса("storageCode")
				.ОписаниеПараметра("Код склада, например 0897")
				.Обязательный()
			.ПараметрЗапроса("productFilter")
				.ОписаниеПараметра("Коды номенклатуры через запятую")
		.Ответ(200)
			.ОписаниеОтвета("Остатки получены")
			.ТипОтвета("application/json")
			.СхемаОтвета("ОстаткиСклада_Ответ")
		.Ответ(404)
			.ОписаниеОтвета("Склад не найден")
	.Сформировать();

	Возврат Методы;

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

Схемы объектов (ОстаткиСклада_Ответ и вложенные) описываются аналогично — свойствами с типом, описанием и примером. Точные имена функций модуля и методов построителя сверяйте с документацией той версии расширения, которую ставите: проект развивается, и API построителя дополняется.

Проверка параметров и ответов

Расширение умеет проверять входящий запрос по описанию — обязательность, типы, допустимые значения — и возвращать понятную ошибку 4xx до выполнения вашей логики. Аналогично можно проверять, что ответ соответствует обещанной схеме. Для этого в начале и в конце обработчика HTTP-сервиса вызываются функции проверки из расширения (см. раздел документации о контроле входящих данных).

Проверку ответа я включаю на тестовых стендах и отключаю в рабочей базе, если сервис нагружен: она полезна для отлова расхождений, но стоит времени на каждом вызове.

Вариант 2: спецификация в макете и свой метод

Если ставить сторонние расширения нельзя (политика безопасности заказчика, сертифицированная конфигурация), спецификацию пишут руками в YAML или JSON и отдают из базы.

  1. Добавьте в конфигурацию (или своё расширение) макет типа «Текстовый документ» СпецификацияOpenAPI с JSON-спецификацией.
  2. Добавьте в HTTP-сервис шаблон /openapi.json с методом GET:
1С
Функция OpenAPIGET(Запрос)

	ТекстСпецификации = ПолучитьОбщийМакет("СпецификацияOpenAPI").ПолучитьТекст();

	Ответ = Новый HTTPСервисОтвет(200);
	Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
	Ответ.УстановитьТелоИзСтроки(ТекстСпецификации, КодировкаТекста.UTF8,
		ИспользованиеByteOrderMark.НеИспользовать);
	Возврат Ответ;

КонецФункции
  1. Покажите спецификацию в любом интерфейсе документации: Swagger UI, Redoc и аналоги умеют загружать спецификацию по URL. Страницу можно отдать ещё одним методом сервиса или разместить на внутреннем портале.

Минус ручного подхода очевиден: спецификация не связана с кодом. Я компенсирую это правилом в команде — изменение HTTP-сервиса без изменения макета спецификации не проходит ревью.

Публикация и веб-сервер

Независимо от варианта, проверьте публикацию:

  • HTTP-сервисы (и HTTP-сервисы расширений) отмечены к публикации;
  • для документации без авторизации — отдельная публикация или отдельный сервис с анонимным доступом только к описанию, но не к данным;
  • после изменения состава сервисов база переопубликована, веб-сервер перезапущен.

Не открывайте Swagger рабочей базы в интернет без авторизации. Документация раскрывает структуру API, а кнопка «попробовать» превращает её в удобный инструмент для любого посетителя.

CORS: когда браузер блокирует запросы

Если страница документации открыта с того же адреса, что и API (как у расширения: /hs/swagger в той же публикации), CORS не нужен. Проблемы начинаются, когда документация или фронтенд живут на другом домене: браузер отправляет предварительный запрос OPTIONS и ждёт заголовки Access-Control-Allow-*.

Две сложности:

  • предварительный запрос приходит без авторизации, и 1С отвечает на него 401 ещё до вашего обработчика;
  • заголовки, добавленные в конфигурации веб-сервера, не всегда попадают в ответ, который формирует модуль 1С.

Надёжнее всего решать CORS на веб-сервере. Пример для Apache (нужны модули mod_headers и mod_rewrite):

apache
<Location "/erp/hs/">
    Header always set Access-Control-Allow-Origin "https://docs.example.ru"
    Header always set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
    Header always set Access-Control-Allow-Headers "Authorization, Content-Type"
</Location>

RewriteEngine On
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^/erp/hs/ - [R=204,L]

always нужен, чтобы заголовки добавлялись и к ответам, сформированным модулем 1С, и к ошибкам. Правило RewriteRule отвечает на предварительный запрос сам, не передавая его в 1С. Вместо конкретного домена не ставьте *, если используется авторизация: браузер такой ответ не примет, да и с точки зрения безопасности это плохая идея.

Swagger для 1С: CORS как пропускной пункт между доменом документации и API
Swagger для 1С: CORS как пропускной пункт между доменом документации и API

Типичные ошибки

  • 404 на /hs/swagger. Нет флажка «Публиковать HTTP-сервисы расширений по умолчанию» или веб-сервер не перезапущен.
  • Документация пустая. Имя модуля-описания не совпадает с именем HTTP-сервиса по шаблону или функции описания не экспортные.
  • Типы расходятся. В описании integer, а сервис отдаёт число строкой с запятой («541,5»). Отдавайте числа числами, даты — в ISO 8601, и описывайте именно то, что отдаёте.
  • Swagger показывает, а запрос не проходит. CORS или авторизация: проверьте ответ на OPTIONS в инструментах разработчика браузера.
  • Документация открыта всем. Закройте авторизацией или вынесите в отдельную публикацию.
Документация API — часть контракта интеграции. Если она живёт отдельно от кода, через полгода ей перестают верить.

Проектирую и документирую API 1С для сайтов, маркетплейсов и внутренних сервисов в рамках интеграции 1С по API; публикацию, HTTPS и CORS настраиваю в рамках веб-доступа к 1С.

Коротко

  • Платформа 1С не генерирует OpenAPI — нужен сторонний механизм или ручная спецификация.
  • Открытое расширение swagger-1c строит спецификацию по модулям-описаниям <Сервис>Описание и отдаёт UI по /hs/swagger/index.html.
  • Без флажка «Публиковать HTTP-сервисы расширений по умолчанию» документация недоступна.
  • Без расширений храните спецификацию в макете и отдавайте методом GET /openapi.json.
  • CORS решайте на веб-сервере и не открывайте документацию рабочей базы без авторизации.