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

См. также

Интеграция Альфа Авто 5 / Альфа Авто 6 и AUTOCRM / Инфотек

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

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

36000 руб.

03.08.2020    15748    10    17    

11

Интеграция 1С — Битрикс24. Обмен задачами

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

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

5040 руб.

04.05.2021    17551    6    15    

13

Интеграция с сервисом vetmanager

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

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

12000 руб.

02.02.2021    16360    42    49    

23

[Расширение] БОР-Навигатор.Культура

Зарплата Бюджетный учет WEB-интеграция Обмен с ГосИС Платформа 1С v8.3 Сложные периодические расчеты 1С:Зарплата и кадры государственного учреждения 3 Государственные, бюджетные структуры Россия Бюджетный учет Платные (руб)

Расширение конфигурации, включающее в себя объекты, необходимые для подготовки и сдачи отчета "Штатная численность" системы "БОР-Навигатор.Культура" в программе "1С:Зарплата и кадры государственного учреждения", редакция 3.1.

8400 руб.

01.02.2019    25741    9    0    

7

Заполнение по ИНН или наименованию реквизитов контрагента по данным сайта ФНС

Обмен с ГосИС WEB-интеграция Платформа 1С v8.3 Управляемые формы 1С:Комплексная автоматизация 1.х 1С:Бухгалтерия 2.0 1С:Управление торговлей 10 1С:Управление производственным предприятием 1С:Управление нашей фирмой 1.6 1С:Бухгалтерия государственного учреждения 1С:Документооборот 1С:ERP Управление предприятием 2 1С:Бухгалтерия 3.0 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х Платные (руб)

Обработка является альтернативой механизму, разработанному фирмой 1С и заполняющему реквизиты контрагента по ИНН или наименованию. Не требуется действующей подписки ИТС. Вызывается как внешняя дополнительная обработка, т.е. используется, непосредственно, из карточки контрагента. Заполнение по ИНН или наименованию реквизитов контрагента по данным сайта ФНС (egrul.nalog.ru) для БП 2.0, БП 3.0, БГУ 1.0, БГУ 2.0, УТ 10.3, УТ 11.x, КА 1.1, КА 2.x, УПП 1.x, ERP 2.x, УНФ 1.5, УНФ 1.6, УНФ 3.0, ДО 2.1

2400 руб.

28.04.2016    88584    160    215    

318
Комментарии
В избранное Подписаться на ответы Сортировка: Древо развёрнутое
Свернуть все
1. sergpn 06.10.21 07:38 Сейчас в теме
Добрый день!
А авторизация запросов есть?
2. kuleshov.x 96 06.10.21 09:24 Сейчас в теме
Описание авторизации securityDefinitions пока не реализовано.
3. Ibrogim 1311 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

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