Каталог решений - Swagger для 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
    • Комментарий Получить список пользователей (определение операции)

2. Для работы с конкретным пользователем:

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

3. Для создания нового пользователя:

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

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