Как интегрировать Swagger и 1С для создания красивой и функциональной API-документации с публикацией на IIS?

← На главную

В данном руководстве мы подробно рассмотрим, как можно "подружить" 1С:Предприятие со Swagger (OpenAPI) для создания интерактивной, понятной и хорошо документированной API для ваших HTTP-сервисов. Мы изучим все шаги, начиная от понимания концепций Swagger до настройки веб-сервера IIS и лучших практик оформления документации.

Что такое Swagger и OpenAPI и почему это важно для 1С?

Прежде чем погрузиться в технические детали, давайте разберемся с основными понятиями. Swagger (OpenAPI) – это не просто инструмент, а целая спецификация, язык описания RESTful API, который не зависит от конкретного языка программирования. Его главная цель — сделать REST API понятным как для машин, так и для людей без прямого доступа к исходному коду.

Когда мы говорим "Swagger", мы часто подразумеваем набор инструментов, которые работают с этой спецификацией OpenAPI. К ним относятся:

Swagger UI: Интерактивный веб-интерфейс, который позволяет визуализировать и взаимодействовать с ресурсами вашего API. Это как живая документация, где можно сразу проверять работу методов.
Swagger Editor: Инструмент для создания и редактирования спецификаций OpenAPI.
Swagger Codegen: Генератор кода, который может создавать клиентские библиотеки, серверные заглушки и другую инфраструктуру из спецификации OpenAPI.

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

Подходы к генерации спецификации Swagger для API

Существуют два основных метода создания спецификации Swagger для любого API, которые мы можем рассмотреть для адаптации к 1С:

Генерация Swagger во время выполнения (Runtime Generation): В этом подходе спецификация Swagger генерируется динамически на основе метаданных, которые мы добавляем к нашим ресурсам, методам и контроллерам API. Эти метаданные обычно представляются в виде аннотаций или комментариев в коде. Инструменты Swagger обрабатывают эти метаданные при вызове соответствующих методов и функций, создавая контракт Swagger.
Генерация Swagger во время сборки (Build-time Generation): Здесь спецификация Swagger создается до выполнения API. Комментарии и структуры данных, определенные внутри API, используются для генерации спецификации. Этот подход часто требует некоторого этапа предварительной обработки или сборки.

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

Интеграция Swagger с 1С:Предприятием

Давайте перейдем к самому интересному – как сделать так, чтобы 1С и Swagger "подружились". Платформа 1С:Предприятие предоставляет возможности для создания HTTP-сервисов, которые могут быть основой нашего API. Для организации процесса документирования этих HTTP-сервисов с помощью Swagger существуют специальные решения. Для автоматизации этой задачи можно использовать готовый инструмент для создания и публикации Swagger.json средствами 1С.

Одним из таких примеров является проект на GitHub "swagger-1c". Этот проект позволяет генерировать документацию HTTP-сервисов прямо из конфигурации 1С. Рассмотрим основные шаги и концепции, которые он использует:

1. Создание описаний для HTTP-сервисов

Мы создаем описания для наших HTTP-сервисов внутри общих модулей 1С. Важно соблюдать определенную структуру наименования. Наименование общего модуля должно соответствовать шаблону <Наименование_HTTP_сервиса>Описание. Например, если у нас есть HTTP-сервис МойСервис, мы создадим общий модуль с именем МойСервисОписание.

Внутри такого модуля мы описываем методы, параметры, схемы запросов и ответов, используя синтаксис, который может быть преобразован в спецификацию OpenAPI. Это позволяет нам централизованно управлять документацией прямо в 1С.

2. Установка решения

Для использования подобных решений, таких как "swagger-1c", нам потребуется установить его в нашу конфигурацию 1С. Обычно это делается следующим образом:

Создаем расширение в режиме конфигуратора.
Загружаем конфигурацию из файлов, указывая каталог с компонентами решения (например, каталог swagger).

После установки расширения его функциональность становится доступной в нашей базе.

3. Проверка входящих и исходящих данных

Хорошо документированный API – это не только описание, но и надежность. Мы можем реализовать проверку входящих запросов и исходящих ответов, чтобы гарантировать корректность данных. Для этой цели подойдет специализированная подсистема валидации запросов и ответов на соответствие схеме OpenAPI.

Для этого можно использовать обертки функций. Например, мы можем вызывать функции ПроверитьПараметры для валидации входящих данных и ПроверитьОтвет для валидации данных, которые мы отправляем в ответ. Это помогает поддерживать качество API и предотвращать ошибки.

Пример структуры модуля описания (концептуальный):

Предположим, у нас есть HTTP-сервис "Товары" с методом "ПолучитьСписок". В модуле ТоварыОписание мы можем определить что-то вроде:


// В общем модуле ТоварыОписание
Функция ПолучитьСпецификацию() Экспорт

    Спецификация = Новый Структура;
    Спецификация.Вставить("openapi", "3.0.0");
    Спецификация.Вставить("info", Новый Структура("title,version", "API для товаров", "1.0.0"));
    Спецификация.Вставить("paths", ПолучитьПути());

    Возврат Спецификация;

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

Функция ПолучитьПути()

    Пути = Новый Структура;
    
    // Описание метода GET /товары
    Пути.Вставить("/товары", Новый Структура);
    Пути["/товары"].Вставить("get", Новый Структура);
    Пути["/товары"]["get"].Вставить("summary", "Получить список товаров");
    Пути["/товары"]["get"].Вставить("description", "Возвращает полный список товаров с возможностью фильтрации.");
    Пути["/товары"]["get"].Вставить("tags", Новый Массив);
    Пути["/товары"]["get"].tags.Добавить("Товары");
    
    // Параметры метода
    Параметры = Новый Массив;
    Параметр1 = Новый Структура;
    Параметр1.Вставить("name", "фильтрПоГруппе");
    Параметр1.Вставить("in", "query"); // Параметр в строке запроса
    Параметр1.Вставить("description", "Фильтр товаров по группе");
    Параметр1.Вставить("required", Ложь);
    Параметр1.Вставить("schema", Новый Структура("type", "string"));
    Параметры.Добавить(Параметр1);
    Пути["/товары"]["get"].Вставить("parameters", Параметры);
    
    // Ответы метода
    Ответы = Новый Структура;
    Ответ200 = Новый Структура;
    Ответ200.Вставить("description", "Успешный ответ со списком товаров");
    Ответы.Вставить("200", Ответ200);
    Пути["/товары"]["get"].Вставить("responses", Ответы);
    
    Возврат Пути;

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

Конечно, реальные решения, такие как "swagger-1c", могут использовать более абстрактные и удобные механизмы для генерации этой структуры, скрывая часть ручного создания спецификации OpenAPI.

Настройка IIS для работы со Swagger и 1С

После того как мы подготовили наши HTTP-сервисы и настроили их описание, нам нужно опубликовать их на веб-сервере. Internet Information Services (IIS) – распространенный выбор для этих целей. Рассмотрим пошагово, как настроить IIS для публикации 1С и отображения Swagger UI.

1. Установка IIS

Прежде всего, убедитесь, что IIS установлен на вашем сервере. Если нет, мы можем установить его различными способами:

Через Диспетчер серверов: Открываем "Диспетчер серверов", выбираем "Добавить роли и компоненты", следуем мастеру, выбирая "Роль веб-сервера (IIS)" и необходимые компоненты, такие как .NET Framework, ASP.NET. Если такие операции по настройке серверов приходится выполнять часто, используйте платформу для создания программных роботов, чтобы автоматизировать последовательность действий в интерфейсе Windows.
Через PowerShell: Используем командлеты PowerShell для установки роли и компонентов.
Через команду DISM: В командной строке с правами администратора.

Убедитесь, что установлены все необходимые функции, особенно связанные с ASP.NET и расширениями для веб-сервера, так как некоторые решения Swagger могут их использовать.

2. Публикация информационной базы 1С

Следующий шаг – публикация нашей информационной базы 1С с HTTP-сервисами на веб-сервере.

Откройте конфигуратор 1С:Предприятия под пользователем с административными правами.
Перейдите в меню "Администрирование" -> "Публикация на веб-сервере".
В появившемся окне укажите имя публикации (виртуального каталога), выберите веб-сервер (IIS), установите флажки для необходимых HTTP-сервисов и убедитесь, что все опции настроены корректно.
Нажмите кнопку "Опубликовать". 1С автоматически создаст необходимый виртуальный каталог и файлы на IIS.

3. Настройка HTTPS для безопасного соединения

Для обеспечения безопасности внешних соединений настоятельно рекомендуется использовать HTTPS. Для этого нам нужно установить соответствующий TLS-сертификат в IIS.

Получение сертификата: Это может быть сертификат, выданный доверенным центром сертификации (для публичного доступа), или самоподписанный сертификат (для внутренней сети или тестирования).
Установка сертификата в IIS: В "Диспетчере IIS" выберите ваш сервер, затем "Сертификаты сервера". Импортируйте ваш TLS-сертификат.
Добавление привязки сайта: Перейдите к вашему сайту (или виртуальному каталогу публикации 1С) в "Диспетчере IIS". В разделе "Действия" выберите "Привязки...". Добавьте новую привязку:
- Тип: https
- Порт: 443
- IP-адрес: Все неназначенные (или конкретный IP)
- Имя узла: Доменное имя, по которому будет доступен ваш API (например, api.yourcompany.com)
- SSL-сертификат: Выберите установленный вами сертификат из выпадающего списка.

4. Отображение Swagger UI на IIS

Иногда после публикации могут возникнуть проблемы с отображением Swagger UI (например, ошибка 404). Выясним возможные причины и пути решения:

Конфликты URL-маршрутизации: IIS или ASP.NET могут перехватывать запрос до того, как он дойдет до Swagger. Это часто происходит, если корневой URL или какой-либо путь переопределен или обрабатывается другими компонентами.
Отсутствие файлов Swagger UI: Убедитесь, что файлы Swagger UI (HTML, CSS, JS) находятся в корневом каталоге вашего сайта или в соответствующем виртуальном каталоге, который обслуживается IIS. Если вы используете решение, которое генерирует эти файлы, убедитесь, что они корректно развернуты. В некоторых случаях может помочь размещение папки swagger-ui непосредственно в корневом каталоге сайта публикации 1С или в отдельном виртуальном каталоге, к которому есть доступ.
Промежуточное ПО (Middleware): Если вы используете какие-либо фреймворки (например, ServiceStack), проверьте порядок загрузки промежуточного ПО. Иногда перемещение middleware для Swagger выше в конвейере обработки запросов может решить проблему, так как оно должно быть выполнено до того, как другие обработчики перехватят URL.
Перенаправление по умолчанию: Чтобы Swagger UI открывался по умолчанию при обращении к веб-приложению на IIS (например, при обращении к https://api.yourcompany.com/), мы можем настроить перенаправление. Это может быть сделано через файл web.config, настроив правило для перенаправления корневого запроса на путь к Swagger UI (например, /swagger/index.html).