Оглавление:
Введение
Простой пример
Инструменты
Настройка 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:
- Для получение списка пользователей:
- Имя ПользователиСписок
- Синоним user (tag)
- Шаблон /user/list (path)
- Методы:
- HTTP метод GET
- Комментарий Получить список пользователей (определение операции)
- HTTP метод GET
- Для работы с конкретным пользователем:
- Имя Пользователь
- Синоним user (tag)
- Шаблон /user/{userID}
- Методы:
- HTTP метод GET
- Комментарий Получить свойства пользователя (определение операции)
- HTTP метод PATCH
- Комментарий Изменить свойство пользователя (определение операции)
- HTTP метод PUT
- Комментарий Изменить все свойства пользователя (определение операции)
- HTTP метод DELETE
- Комментарий Удалить пользователя (определение операции)
- HTTP метод GET
- Для создания нового пользователя:
- Имя ПользовательНовый
- Синоним user (tag)
- Шаблон /user
- Методы:
- HTTP метод POST
- Комментарий Создать нового пользователя (определение операции)
- HTTP метод POST
Так же платформой были созданы обработчики в модуле 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).
На данный момент сформированная спецификация основана только на метаданных конфигурации. Но мы ее сделаем еще информативнее.
Комментарий по стандарту
В стандартах разработки на ИТС у нас есть такой замечательный документ. Он достаточно подробно показывает как нам правильно описывать свои процедуры и функции.
Воспользуемся данным стандартом, и добавим подробное описание функций в модуле сервиса:
Обновим спецификацию, проверяем что в каждый метод добавилось описание:
Следующим шагом опишем входящие параметры, которые явно заданы в пути (шаблон /user/{userID}):
Обновим спецификацию, проверяем описание параметра userID:
Так как в логике работы некоторых методов подразумевается получение данных из тела запроса или в строке самого запроса, добавим в соответствующие комментарии:
- для методов PUT и POST добавим описание параметра body (ключ-слово библиотеки swagger)
- для метода PATCH добавим описание параметров property и value (напомню, логика обработки данного метода подразумевает изменение конкретного свойства)
Обновим спецификацию, проверяем описание параметра body:
а так же для метода PATCH:
Комментарий не по стандарту
Рассмотрим ситуацию, что по переданному userID пользователь в системе не был найден. Тогда наш сервис должен вернуть код ответа 404. А если в процессе изменения свойства пользователя в базе 1С произошла ошибка (все же пользуются транзакцией с попыткой) то вернем код ответа 500.
Поскольку потребность описать коды ответов HTTP сервиса не предусмотрена в стандарте ИТС, то в комментарии будем добавлять "нестандартный" блок:
// Коды ответов:
// XXX - Описание
//
где XXX - код ответа по стандарту RFC7231.
Дописываем изменения в модуле:
Обновим спецификацию, проверяем блоки Responses:
Заключение
На данный момент, библиотека swagger выпущена как минимально жизнеспособный продукт (MVP). В планах стоят следующие задачи:
- Добавить поддержку формирования спецификации для конфигурации в формате проекта EDT.
- Найти приемлемый способ описания схемы объектов 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"
]
}
}
}
- Научиться связывать спецификации с настройками публикации тестовых база и попробовать автотесты.
Буду рад любой конструктивной критике и предложениям.
Благодарности
Особую благодарность выражаю Овсянкину Андрею за помощь в подготовке данной статьи, а сообществу OneScript за отличный продукт и прекрасное комьюнити.
P.S. Никаких файлов для загрузки, все необходимое доступно по приведенным в статье ссылкам.
