Swagger для 1С. Описание сложной структуры входящих и исходящих данных

04.10.21

Интеграция - WEB-интеграция

Анонс нового функционала 1Script пакета swagger версии 0.5.0.

Пакет swagger - это open source инструмент на языке OneScript, предназначенный для создания спецификаций HTTP сервисов 1С в формате OpenAPI.

  • Помогает поддерживать документацию в актуальном состоянии.
  • Позволяет зафиксировать API еще до реализации.
  • Не требует встраивания в описываемую конфигурацию.
  • Спецификация OpenAPI по сути является промышленным стандартом описания REST API интерфейсов.

Оригинальная статья: Swagger для 1С

Репозиторий проекта: https://github.com/botokash/swagger

Пример описания метода

 
 Описание метода в модуле HTTP сервиса

Быстрый старт

1. Устанавливаем OneScript

2. Устанавливаем пакет swagger

opm install swagger

3. Выгружаем конфигурацию в файлы

4. Генерируем описание Open-API

swagger generate --src-path <Путь к файлам конфигурации> --out <Путь к директории выгрузки> --host <Адрес веб сервера> --onecbase <Тестовая база 1С>

5. Загружаем описание сервиса из файла в директории выгрузки в редактор https://editor.swagger.io/

Дополнительно:

1. Настраиваем Simple-UI

2. Встраиваем актуализацию описания сервиса с помощью скрипта upload.os в пайплайн Gitlab-CI

Swagger:
  stage: Swagger
  script:
    - chcp 65001
    - oscript tools\upload.os -name TEST_SERVICE -path src\configuration -type xml -adminurl http://localhost/onec-swagger-admin/ -host 127.0.0.1 -onecbase TEST_BASE

Описание методов

Методы описываются текстом в модуле HTTP сервиса. Общий шаблон представлен ниже.

// <Описание метода>
//
// Параметры:
//   <Имя параметра> - <Тип данных> - <Описание параметра>
//
// Варианты вызова:
//   <Формат входящих данных>
//
// Варианты ответа:
//   <Формат исходящих данных>
//
// Коды ответов:
//   <Код ответа> - <Тип данных> - <Описание ответа> ИЛИ <Код ответа> - <Описание ответа>
//
Функция <Обработчик метода>(Запрос)
...
КонецФункции

Параметры

Параметры задаются в формате:

  • <Имя параметра> - <Тип данных> - <Описание параметра>

Для тела запроса (PUT и POST) используется имя параметра body.

Для метода PATCH используются имена property и value.

В блоке параметров может быть описана сложная структура входящих данных. Уровень вложенности параметра определяется количеством знаков * перед именем параметра.

Имя сложного типа должно состоять из одного слова и быть уникальным.

Для описания множественных значений перед названием типа должна быть ключевая фраза Массив из.

Для обязательных параметров в тексте описания нужно добавить ключевое слово обязательный.

Для задания списка возможных значений параметра используется символ ~

  • ~ <Значение перечисления 1> - <Описание значения 1>
  • ~ <Значение перечисления 2> - <Описание значения 2>
// Параметры:
//   userID - Строка - Идентификатор пользователя
//   messageId - Строка - Идентификатор сообщения, обязательный
//   body - Массив из Accept - Информация о подтверждении
//    * orderId - Строка - ID заказа
//    * data - Массив из AdditionalData - Дополнительная информация
//     ** name - Строка - Имя свойства
//     ** value - Массив из Строка - Значения свойства
//    * status - Строка - Статус
//     ~ Подтверждено - Статус "Подтверждено"
//     ~ Отклонено - Статус "Отклонено"

Формат данных

Формат входящих и исходящих данных описывается блоками Варианты вызова и Варианты ответа.

// Варианты вызова:
//   application/json
//   application/xml
//
// Варианты ответа:
//   application/json
//   text/html

Коды ответов

Коды ответа указываются в формате "Код - Описание".

Для каждого кода ответа дополнительно можно определить возвращаемое значение. Для этого код ответа должен быть описан по шаблону "Код - Возвращаемое значение - Описание".

Поддерживается сложная структура возвращаемых данных.

// Коды ответов:
//   200 - Массив из Order - Массив заказов
//    * orderId - Строка - ID заказа
//    * status - Строка - Статус
//    * taskList - Массив из Task - Массив задач
//     ** taskId - Строка - ID задания
//     ** taskNumber - Строка - Номер задания
//   400 - Ошибка выполнения
//   401 - Некорректный токен авторизации

 

swagger rest open-api onescript

См. также

WEB-интеграция 8.3.8 Конфигурации 1cv8 Автомобили, автосервисы Беларусь Украина Россия Казахстан Управленческий учет Платные (руб)

Расширение предназначено для конфигурации "1С:Предприятие 8. Управление Автотранспортом. ПРОФ". Функционал модуля: 1. Заполнение регистров сведений по подсистеме "Мониторинг", а именно: события по мониторингу, координаты по мониторингу, пробег и расход по мониторингу, текущее местоположение ТС по мониторингу 2. Заполнение путевого листа: пробег по мониторингу, время выезда/заезда, табличная часть ГСМ, места стоянок по геозонам. 3. Отчеты по данным загруженным в регистры сведений. 4. Предусмотрена автоматическая загрузка данных в фоновом режиме (условия работы данной загрузке читайте в описании товара) Модуль работает без включенной константы по настройкам мониторинга. Модуль формы предоставляется с открытым кодом, общий модуль защищен. Любой заинтересованный пользователь, имеет возможность скачать демо-версию расширения.

22656 руб.

25.05.2021    13439    39    8    

15

Управление взаимоотношениями с клиентами (CRM) WEB-интеграция Анализ продаж Системный администратор Программист Пользователь Платформа 1С v8.3 1С:ERP Управление предприятием 2 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х Управленческий учет Платные (руб)

Подсистема интеграции Amo CRM с 1С: технические требования, порядок работы, возможности, доработки и обновления. Бесплатный период техподдержки - 1 месяц.

60000 руб.

07.05.2019    31985    62    41    

23

Сайты и интернет-магазины WEB-интеграция Системный администратор Программист Пользователь Платформа 1С v8.3 Конфигурации 1cv8 1С:Управление торговлей 11 Автомобили, автосервисы Россия Управленческий учет Платные (руб)

Интеграционный модуль обмена между конфигурацией Альфа Авто 5 и Альфа Авто 6 и порталом AUTOCRM. Данный модуль универсален. Позволяет работать с несколькими обменами AUTOCRM разных брендов в одной информационной базе в ручном и автоматическом режиме.

36000 руб.

03.08.2020    16838    15    19    

15

WEB-интеграция Программист Платформа 1С v8.3 Бухгалтерский учет 1С:Бухгалтерия 3.0 Бытовые услуги, сервис Платные (руб)

Внешняя обработка разрабатывалась для загрузки документов из Ветменеджер в 1С: Бухгалтерия 3.0

12000 руб.

02.02.2021    17080    46    49    

26

Сайты и интернет-магазины Интеграция WEB-интеграция Платформа 1С v8.3 Конфигурации 1cv8 Управленческий учет Платные (руб)

Интеграция 1С и Битрикс 24. Разработка имеет двухстороннюю синхронизацию 1С и Bitrix24 задачами. Решение позволяет создавать пользователя в 1С из Битрикс24 и наоборот. Данная разработка технически подходит под все основные конфигурации линейки продуктов 1С:Предприятие 8.3 (платформа начиная с 8.3.23). При приобретении предоставляется 1 месяц бесплатных обновлений разработки. Доступна демо-версия продукта с подключением Вашего Битрикс24

5040 руб.

04.05.2021    19142    10    17    

16
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. sergpn 06.10.21 07:38 Сейчас в теме
Добрый день!
А авторизация запросов есть?
2. kuleshov.x 97 06.10.21 09:24 Сейчас в теме
Описание авторизации securityDefinitions пока не реализовано.
3. Ibrogim 1319 06.10.21 15:47 Сейчас в теме
Классно, однозначно +. были попытки сделать такое без OneScript . грубо говоря можно в случае определённого значения определённого параметра возвращать описание. и тогда можно пробежавшись по всем http сервисам простой обработкой создать yaml для Swagger.
4. JohnyDeath 301 11.10.21 09:25 Сейчас в теме
На самом деле очень часть надо "ссылаться" на одни и те же типы данных в разных функциях.
Например
//    * status - Строка - Статус
//     ~ Подтверждено - Статус "Подтверждено"
//     ~ Отклонено - Статус "Отклонено"

наверняка будет еще где-то использоваться, как и "массив заказов".
В OpenAPI для этого есть блок "definitions", но как это сделать описанием к функциям я не знаю.
Возможно сейчас придут умные люди и расскажут про свои методы описаний сервисов.

Вот подход, где описанием являются общие модули. https://github.com/zerobig/swagger-1c
5. VVi3ard 52 15.10.21 14:13 Сейчас в теме
(4)
В OpenAPI для этого есть блок "definitions", но как это сделать описанием к функциям я не знаю.

Согласен, именно из за использования ссылок лучше пользоваться онлайн инструментами, с удобными конструкторами, например stoplight.io
Описать в них сервис конструктором намного проще чем пытаться это делать в конфигураторе.

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

postman просит json shema для конкретного метода, и как получить это из общего большого yml не понятно.

Вот интересно есть тут кто то кто использует swagger + json schema для проверки структуры ответа с использованием postman.
6. VVi3ard 52 15.10.21 14:19 Сейчас в теме
(4)
Вот подход, где описанием являются общие модули. https://github.com/zerobig/swagger-1c


Не понимаю зачем это нужно, если хочешь писать почему сразу не писать на yml ?

У автора данной статьи и в проекте на гитхабе вводится третья сущность которая потом транслируется в yml и я не сказал бы что их синтаксис проще и лаконичнее чем исходный yml файл.


На мой взгляд описание сервисов лучше начинать с хорошего конструктора что бы изучить все возможности синтаксиса, а позже уже можно править yml файл руками (так часто быстрее чем в конструкторе).


Я понимаю если бы генерация проводилась автоматически на основании типов (как например для Ruby rswag gem), но какой смысл делать это через промежуточные описания?
7. JohnyDeath 301 15.10.21 14:59 Сейчас в теме
(6)
Не понимаю зачем это нужно, если хочешь писать почему сразу не писать на yml ?

Мне кажется, что прелесть того репозитория в том, что после публикации базы и ее http-сервисов мы сразу имеем онлайн-описание этих сервисов по тому же адресу, где и сама база опубликована. Не надо ничего отдельного держать/генерировать/разворачивать
8. AlexZm 02.02.22 00:23 Сейчас в теме
Добрый день! Добавил в IIS приложение и при проверке запросом http://localhost/onec-swagger-admin/list.os получаю следующую ошибку:
Ошибка HTTP 404.17 — Not Found
Содержимое запроса является сценарием и не будет обрабатываться обработчиком файла статистики.
The requested content appears to be script and will not be served by the static file handler

Подскажите как побороть данную ошибку? Спасибо
Прикрепленные файлы:
Оставьте свое сообщение