Как настроить Swagger для 1С и исправить ошибку с отсутствующими каталогами

Программист 1С v8.3 (Управляемые формы) IT и автоматизация бизнеса
← На главную

Реализация автодокументирования API в среде 1С через Swagger (OpenAPI) — задача крайне востребованная, но технически сложная. Часто разработчики сталкиваются с тем, что популярные инструкции и open-source проекты содержат неточности или устаревшие данные. В этой статье мы подробно разберем, как преодолеть типичные ошибки при настройке решения на базе OneScript, настроить веб-сервер и обеспечить корректную передачу типов данных.

Разбор ошибки с путями: rest-admin или spec-admin

Проанализируем типичную ситуацию: при попытке поднять проект swagger от botokash или аналогичные решения на базе Simple-UI, программисты часто не обнаруживают каталог simple-ui\rest-admin, указанный в старых мануалах. Рассмотрим причину возникновения этой проблемы и способ ее решения.

В процессе развития проекта структура каталогов была изменена. Если вы не находите папку rest-admin, это означает, что вы используете версию, в которой произошло переименование. Выясним, что нужно изменить в настройках:

  1. Каталог simple-ui\rest-admin теперь называется simple-ui\spec-admin.
  2. Файл логики list.os, отвечающий за формирование списка сервисов, перемещен в новый каталог без изменения внутренней структуры кода.
  3. При настройке виртуального каталога в IIS или Apache необходимо указывать путь именно к spec-admin.

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

C:\inetpub\wwwroot\swagger\simple-ui\spec-admin\list.os

Настройка окружения: OneScript и IIS

Одной из главных причин возникновения ошибки 500 (Internal Server Error) является неправильная конфигурация веб-сервера для исполнения скриптов .os. Разберем по шагам, как подготовить сервер к работе со Swagger-генератором.

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


opm install cmdline
opm install json

Теперь проанализируем настройку IIS. Чтобы веб-сервер понимал, как обрабатывать запросы к .os файлам, необходимо добавить Handler Mapping (Сопоставление обработчиков). Рассмотрим алгоритм:

  1. Откроем диспетчер служб IIS и выберем наш сайт или виртуальный каталог.
  2. Перейдем в раздел "Сопоставление обработчиков".
  3. Добавим "Добавить сопоставление модуля" (Add Module Mapping).
  4. Путь запроса: *.os.
  5. Модуль: FastCgiModule (если не установлен, его нужно добавить через компоненты Windows).
  6. Исполняемый файл: путь к oscript.exe.
  7. Название: OneScriptHandler.

Важный момент: убедимся, что у пользователя, под которым запущен пул приложений IIS (например, IIS AppPool\DefaultAppPool), есть права на чтение каталога с OneScript и выполнение исполняемых файлов.

Проблема типизации данных в 1С

Одной из самых острых проблем при формировании swagger.json для 1С является отсутствие строгой типизации параметров в HTTP-сервисах 1С. Выясним, почему это мешает генерации документации. В стандарте Swagger (OpenAPI) каждый параметр должен иметь четкий тип (integer, string, boolean и т.д.). В 1С программист зачастую извлекает параметры из тела запроса или URL вручную, и тип параметра определяется только в момент исполнения кода.

Посмотрим на пример описания параметра, который ожидает Swagger:


"parameters": [
  {
    "name": "orderId",
    "in": "path",
    "required": true,
    "type": "integer",
    "format": "int64"
  }
]

В 1С же мы часто видим подобный код обработки:


ИдентификаторЗаказа = Запрос.ПараметрыURL.Получить("orderId");
// Здесь тип ИдентификаторЗаказа еще не определен жестко метаданными

Чтобы решить эту проблему при автоматической генерации Swagger, рекомендуется использовать специальные комментарии (аннотации) в модуле HTTP-сервиса. Разберем, как современные парсеры (например, используемые в onescript-swagger) позволяют обходить это ограничение. Мы можем добавлять описания типов прямо в заголовке метода:


// @Summary Получить данные заказа
// @Param orderId path integer true "Идентификатор заказа"
// @Response 200 {Structure} ДанныеЗаказа

Парсер считывает эти строки и подставляет их в итоговый JSON-файл, что позволяет сторонним разработчикам видеть корректную структуру API.

Современные альтернативы сторонним скриптам

Проанализируем ситуацию с развитием платформы. Если ручная настройка OneScript кажется слишком трудоемкой, стоит обратить внимание на встроенные возможности последних версий 1С. Начиная с версии 8.3.24, платформа получила встроенную поддержку генерации описаний OpenAPI для стандартного интерфейса OData.

Рассмотрим, как это работает: При публикации информационной базы на веб-сервере достаточно включить стандартный интерфейс OData. Спецификацию в формате Swagger можно получить, обратившись по специальному адресу:

http://server/base/odata/standard.odata/$openapi

Однако, если вам нужно описание именно ваших кастомных HTTP-сервисов, а не всей базы через OData, то использование инструментов на базе OneScript или EDT (Enterprise Development Tools) остается приоритетным вариантом. В EDT существуют плагины, которые позволяют визуализировать и тестировать HTTP-сервисы в интерфейсе, аналогичном Swagger UI, прямо в процессе разработки.

Резюме по устранению ошибок

Если при попытке запустить Swagger вы все еще получаете ошибку 500, выполните финальную проверку следующих пунктов:

Использование Swagger в 1С значительно упрощает интеграцию с современными фронтенд-системами и мобильными приложениями. Несмотря на сложности первоначальной настройки, создание единого стандарта документации окупается при первом же изменении состава API или смене команды разработки.

← На главную