Пакет swagger - это open source инструмент на языке OneScript, предназначенный для создания спецификаций HTTP сервисов 1С в формате OpenAPI.
- Помогает поддерживать документацию в актуальном состоянии.
- Позволяет зафиксировать API еще до реализации.
- Не требует встраивания в описываемую конфигурацию.
- Спецификация OpenAPI по сути является промышленным стандартом описания REST API интерфейсов.
Оригинальная статья: Swagger для 1С
Репозиторий проекта: https://github.com/botokash/swagger
Пример описания метода
Быстрый старт
1. Устанавливаем OneScript
2. Устанавливаем пакет swagger
opm install swagger
3. Выгружаем конфигурацию в файлы
4. Генерируем описание Open-API
swagger generate --src-path <Путь к файлам конфигурации> --out <Путь к директории выгрузки> --host <Адрес веб сервера> --onecbase <Тестовая база 1С>
5. Загружаем описание сервиса из файла в директории выгрузки в редактор https://editor.swagger.io/
Дополнительно:
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 - Некорректный токен авторизации
