swagger

13 октября 2019 18:03

Скрипты OneScript


Формирование swagger спецификации на основании метаданных конфигурации 1С.

Пара ссылок по теме

Wiki

Описание формата

Сайт Swagger

Swagger Editor (быстро проверить свои jsonчики)

Принцип работы библиотеки

На основании выгрузки конфигурации в файлы (в будущем добавлю поддержку edt) производится поиск/парсинг/описание http сервисов и преобразование полученных данных в спецификацию swagger (json на выходе).

Парсинг модуля сервиса предназначен для комментариев вызовов по стандрату ИТС

Дополнительное описание методов

Параметры

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

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

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

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

// Параметры:
//   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

// класс для парсинга метаданных конфигурации
ПарсерМетаданных = Новый ПарсерМетаданных();

Если ПарсерМетаданных.ПодключитьКонфигурацию(ПутьВыгрузкиКонфигурации, "xml") Тогда

    // без параметров читаем все сервисы, возможен отбор по названию через запятую
    ПарсерМетаданных.ВыполнитьПарсингКонфигурации();

    Для Каждого КЗ Из ПарсерМетаданных.ВнутренниеОписанияСервисов Цикл

        ОписаниеСервиса = КЗ.Значение;
        
        // ОписаниеСервиса["Хост"] = "1c-subs";
        // ОписаниеСервиса["КорневойURL"] = "/perf-metrics/hs" + ОписаниеСервиса["КорневойURL"];

        // класс генерации спецификации, создаем на результате работы ПарсерМетаданных
        ГенераторСпецификации = Новый ГенераторСпецификации(ОписаниеСервиса);

        ГенераторСпецификации.ПрочитатьОписаниеСервиса();

        // ПолучитьСпецификацию() - возвращает текст
        // СохранитьСпецификацию(КаталогВыгрузки, "json") - сохраняет в файл
        Сообщить(ГенераторСпецификации.ПолучитьСпецификацию());

    КонецЦикла;

Иначе
    Сообщить("Не удалось подключить конфигурацию!", СтатусСообщения.Внимание);
КонецЕсли;

Пример получения спецификации в скрипте example_specgenerator.os

Simple-UI

Пример реализация быстрого каталогизатора спецификаций внутри компании. Используем готовый swagger-ui, rest сервисы на oscript и IIS.

  1. Создаем виртуальный каталог "onec-swagger-ui", закидываем внутрь dist из репозитария swagger-ui.
  2. Создаем приложение "onec-swagger-admin", внутрь ложим rest-admin.
  3. Заменяем index.html на новый.
  4. В новом index.html указываем в переменной admin_url свой сервер IIS публикаци rest-admin.
  5. Загрузка спецификаций будет происходить скриптом upload.os следующей командой: oscript .\upload.os -name ИмяПроекта -path ПутьКВыгрузкеФайлов -type xml -adminurl http://ВашСервер/onec-swagger-admin/
Сайт 0

См. также

anti_swagger

Комментарии

Модератору