Swagger для 1С.

21.10.2019 9 Comments

Интеграция с WEB, Разработка, Системная интеграция

,















    Пример документации.PNG
    Новое приложение IIS.PNG
    Swagger-UI на IIS.PNG
    Swagger-UI базовый.PNG
    Свойства нового сервиса.PNG
    Свойства шаблона ПользователиСписок.png
    Свойства шаблона Пользователь.png
    Свойства шаблона ПользовательНовый.png
    Пример результат 1.PNG
    Метод PUT.PNG
    Метод PUT 2.PNG
    Метод PUT 3.PNG
    Метод PUT 4.PNG
    Метод PATCH.PNG
    Метод PUT 5.PNG

Решение для формирования Swagger спецификаций, описывающих HTTP сервисы конфигураций 1С.

Оглавление:

Введение
Простой пример
Инструменты
Настройка Simple-UI
Первый результат
Делаем красиво
Заключение
Благодарности

 

Введение

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

Что же такое Swagger спецификация? Небольшая выдержка с Wiki:

The OpenAPI Specification (изначально известная как Swagger Specification)— формализованная спецификация и экосистема множества инструментов, предоставляющая интерфейс между front-end системами, кодом библиотек низкого уровня и коммерческими решениями в виде API. Вместе с тем, спецификация построена таким образом, что не зависит от языков программирования, и удобна в использовании как человеком, так и машиной.

Относительно назначения, OpenAPI рассматривается как универсальный интерфейс для пользователей (клиентов) по взаимодействию с сервисами (серверами). Если спроектирована спецификация для некоторого сервиса, то на её основании можно генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и др. Для этих действий имеется большой набор инструментов для различных языков программирования и платформ.

Все описание создаваемых нами HTTP сервисов на платформе 1С должно бы выглядеть так:

Это позволит публиковать документацию сервисов 1С в общепринятом, стандартизованном формате, общаясь с внешними командами общепринятом в среде профессионалов языке спецификаций API, не дополняя общение постыдными фразами вида "ой, у нас 1С, у нас нет Swagger, наш программист сейчас напишет все в Ворде". Swagger — это документация которая не врет и не отстает от основного кода, поскольку является его продолжением и создается автоматически. Никаких больше "документаций сервиса в Word!"

Что бы получить желаемый результат, мной была создана OneScript библиотека — swagger, которая реализует формирование второй редакции OpenAPI спецификации.

 

Простой пример

Более детальное описание возможностей библиотеки swagger я рассмотрю на примере создания нового HTTP сервиса в произвольной конфигурации. Нижеизложенный текст будет показывать сопоставление содержимого метаданных/модулей конфигурации с визуальным представлением генерируемой спецификации.

 

Постановка задачи

Возникла потребность создать API управления доступом в систему 1С. Необходимые возможности:

  • Получить список всех пользователей
  • Получить все свойства пользователя
  • Изменить все свойства пользователя
  • Изменить одно свойство пользователя
  • Создать нового пользователя
  • Удалить существующего пользователя

 

Подготовка метаданных

Добавим в дерево метаданных новый HTTP сервис:

  • Имя UserAPI (имя сервиса)
  • Синоним API управления доступом (описание сервиса)
  • Комментарий 1.0 (версия сервиса)

Общее описание сервиса

Создадим наборы шаблонов URL:

  1. Для получение списка пользователей:
  • Имя ПользователиСписок
  • Синоним user (tag)
  • Шаблон /user/list (path)
  • Методы:
    • HTTP метод GET
      • Комментарий Получить список пользователей (определение операции)

  1. Для работы с конкретным пользователем:
  • Имя Пользователь
  • Синоним user (tag)
  • Шаблон /user/{userID}
  • Методы:
    • HTTP метод GET
      • Комментарий Получить свойства пользователя (определение операции)
    • HTTP метод PATCH
      • Комментарий Изменить свойство пользователя (определение операции)
    • HTTP метод PUT
      • Комментарий Изменить все свойства пользователя (определение операции)
    • HTTP метод DELETE
      • Комментарий Удалить пользователя (определение операции)

  1. Для создания нового пользователя:
  • Имя ПользовательНовый
  • Синоним user (tag)
  • Шаблон /user
  • Методы:
    • HTTP метод POST
      • Комментарий Создать нового пользователя (определение операции)

Так же платформой были созданы обработчики в модуле HTTP сервиса:

 

 Модуль HTTP сервиса

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

 

Инструменты

Установим или обновим OneScript до актуальной версии (на момент написания статьи 1.1.1). Далее установим библиотеку swagger:

opm install swagger

Так же потребуется наличие IIS на своей машине или ином сервере. Но все примеры ниже будут в рамках localhost.

Скачаем содержимое папки dist из официального репозитория Swagger-UI.

Скачаем содержимое папки simple-ui из репозитория библиотеки swagger.

 

Настройка Simple-UI

Simple-UI представляет собой пример каталогизатора спецификаций, позволяющий хранить, актуализировать и отдавать спецификации по запросу. Выполнен в виде HTTP сервисов на OneScript. Так же приведен пример модификацию Swagger-UI для взаимодействия с нашим каталогизатором.

 

Развертывание spec-admin

Описание, создание и публикация HTTP сервисов на OneScript хорошо рассмотрены тут и тут.

В IIS добавим новое приложение:

 

Проверим готовность сервиса обычным GET запросом на:

http://localhost/onec-swagger-admin/list.os

В теле ответа от сервиса мы должны получить "[]".

 

Развертывание Swagger-UI

В IIS добавим новый виртуальный каталог:

Проверим в браузере:

Далее заменим файл index.html в каталоге onec-swagger-ui на аналогичный файл из Simple-UI.

Завершающим этапом откроем в любом редакторе новый файл index.html и заменим в строчке:

var admin_url = 'http://localhost/onec-swagger-admin/'

"localhost" на адрес вашего IIS сервера:

var admin_url = 'http://ВашСерверIIS/onec-swagger-admin/'

 

Первый результат

Из репозитория библиотеки swagger скачаем скрипт upload.os. У нас уже есть выгруженная в файлы конфигурация D:ПримерКонфигурация.

Открываем терминал и выполним следующую команду:

oscript upload.os -name SimpleAPI -path D:ПримерКонфигурация -type xml -adminurl localhost/onec-swagger-admin/

Если команда прошла без ошибок, любуемся результатом на http://localhost/onec-swagger-ui/

 

Делаем красиво

Рассмотрим более подробное описание метода PUT /user/{userID}:

Как мы видим, библиотекой swagger в сформированной спецификации явно описан параметр userID с пометкой входящий и расположением в пути запроса. Так же по умолчанию подставляется единственный код ответа сервиса — 200 (см. стандарт RFC7231) и тип данных в теле ответа считается обычным текстом (см. стандарт RFC6838).

На данный момент сформированная спецификация основана только на метаданных конфигурации. Но мы ее сделаем еще информативнее.

 

Комментарий по стандарту

В стандартах разработки на ИТС у нас есть такой замечательный документ. Он достаточно подробно показывает как нам правильно описывать свои процедуры и функции.

Воспользуемся данным стандартом, и добавим подробное описание функций в модуле сервиса:

 

 Модуль HTTP сервиса

Обновим спецификацию, проверяем что в каждый метод добавилось описание:

Следующим шагом опишем входящие параметры, которые явно заданы в пути (шаблон /user/{userID}):

 

 Модуль HTTP сервиса

Обновим спецификацию, проверяем описание параметра userID:

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

  • для методов PUT и POST добавим описание параметра body (ключ-слово библиотеки swagger)
  • для метода PATCH добавим описание параметров property и value (напомню, логика обработки данного метода подразумевает изменение конкретного свойства)
 

 Модуль HTTP сервиса

Обновим спецификацию, проверяем описание параметра body:

а так же для метода PATCH:

 

Комментарий не по стандарту

Рассмотрим ситуацию, что по переданному userID пользователь в системе не был найден. Тогда наш сервис должен вернуть код ответа 404. А если в процессе изменения свойства пользователя в базе 1С произошла ошибка (все же пользуются транзакцией с попыткой) то вернем код ответа 500.

Поскольку потребность описать коды ответов HTTP сервиса не предусмотрена в стандарте ИТС, то в комментарии будем добавлять "нестандартный" блок:

// Коды ответов:
//   XXX - Описание
//

где XXX — код ответа по стандарту RFC7231.

Дописываем изменения в модуле:

 

 Модуль HTTP сервиса

Обновим спецификацию, проверяем блоки Responses:

 

Заключение

На данный момент, библиотека swagger выпущена как минимально жизнеспособный продукт (MVP). В планах стоят следующие задачи:

  1. Добавить поддержку формирования спецификации для конфигурации в формате проекта EDT.
  2. Найти приемлемый способ описания схемы объектов API в конфигурации 1С. Пока я вижу этот момент как описание в комментарии, примерно следующим образом:
// Параметры:
//   body - Объект(json):UserType - Пользователь
//    * Name - Строка - Имя
//    * ShowInList - Булево - Показывать в списке
//    * Roles - Массив из Строка - перечень ролей

что будет соответствовать объекту в json:

{
"Name": "Name",
"ShowInList": true,
"Roles": [
"Role"
]
}

и в спецификации будет описание в схеме:

{
"definitions": {
"User": {
"type": "object",
"discriminator": "UserType",
"properties": {
"Name": {
"type": "string"
},
"ShowInList": {
"type": "boolean"
},
"Roles": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"Name",
"ShowInList",
"Roles"
]
}
}
}
  1. Научиться связывать спецификации с настройками публикации тестовых база и попробовать автотесты.

Буду рад любой конструктивной критике и предложениям.

 

Благодарности

Особую благодарность выражаю Овсянкину Андрею за помощь в подготовке данной статьи, а сообществу OneScript за отличный продукт и прекрасное комьюнити.

 

P.S. Никаких файлов для загрузки, все необходимое доступно по приведенным в статье ссылкам.

Related Posts

9 Comments

  1. YPermitin

    (0) Очень круто!

    Reply ↓
  2. chg

    Интересно, подпишусь

    Reply ↓
  3. ZeratulAyuris

    Очень своевременно, спасибо!

    Reply ↓
  4. Жолтокнижниг

    Качественно.

    Даешь swagger в 1с массы.

    Reply ↓
  5. tanat74

    Большое спасибо. Очень давно искал такой механизм.

    Reply ↓
  6. CodeNull

    Здравствуйте. Весьма годный и нужный инструмент. Но как вы сами написали, не хватает описания body для post запросов. Например, в нашем проекте post запросы это самая объемная часть, body некоторых весьма сложный по структуре (много полей и вложимость).

    А что насчёт описания ответа (возвращаемое значение)?

    Reply ↓
  7. botokash

    (6) Как я писал в заключении описание схемы данных, как в теле запроса, так и в теле ответа, обязательно будет в следующих релизах библиотеки. Сейчас вопрос стоит в том, как лучше сделать. Ну и конечно вопрос времени, пока занят другим проектом. Можете добавить репозиторий библиотеки на гитхабе в наблюдение, не пропустите обновление )

    Reply ↓
  8. Evil Beaver

    Столкнулся с обратной задачей — есть готовая спецификация API в виде OpenApi json и нужно сделать веб-сервис. Для многих языков есть готовые генераторы классов под такую спецификацию. Может автор и для 1С сделает? Надо всего-то XML с описанием веб-сервиса сгенерировать и модуль с заглушками методов. А потом это можно в исходники 1С подложить и готово!

    Reply ↓
  9. botokash

    (8) Автор с самого начала задумывался над кодогенерацией) Пока проблема с наличием свободного времени.

    Reply ↓

Leave a Comment

Ваш адрес email не будет опубликован. Обязательные поля помечены *