Библиотека для написания и тестирования документации к http-сервисам 1С с помощью Swagger

Небольшая библиотека, которая позволяет программисту описать документацию буквально в несколько строк. Хотя вру, строк может быть довольно много, но пишется такая документация быстро.

Как это работает?

Главным объектом библиотеки является Сервис, который может включать в себя любое количество шаблонов URL, что позволяет объединять документацию для довольно разных API в один документ.

Сервис = Обработки.oapi_Сервис.Создать();
Сервис.КраткоеОписание = "Бар ""Бухарин""";
Сервис.ПолноеОписание = "API нашего замечательного бара";
Сервис.ИспользоватьСхемыДанных = Истина;
Сервис.ДобавитьСервер("https://api.buhbuharin.io/");

Шаблон URL описывает конечный адрес (endpoint) http-cервиса

Шаблон = Сервис.ДобавитьШаблонURL("/shot", "Метод для заказа напитка");

В шаблон добавляются варианты возможных запросов и ответов.

Объект Сервис имеет методы ТипСтруктура, ТипСоответствие, ТипМассив, ТипЧисло, ТипСтрока, которые возращают "обертки" над встроенными типами. Обертка нужна, чтобы добавлять нормально описание типов и задавать схемы данных.

Метод = Шаблон.ДобавитьМетод("POST", "Заказ напитка");
Метод.ПолноеОписание  = "Возвращает цену напитка";

// Описываем тело входящего запроса
Заказ = Сервис.ТипСтруктура("Данные заказа", "Order");
Заказ.Вставить("drink_name" , Сервис.ТипСтрока("Водочка", "Название напитка"));
Заказ.Вставить("count" , Сервис.ТипЧисло(5, "Количество шотов", Ложь));
Метод.ДобавитьВариантЗапроса("Заказ напитка").ДобавитьДанные(Заказ);

// Описываем структуру возвращаемых данных
ДанныеЗаказа = Сервис.ТипСтруктура("Информация о напитке", "OrderInfo");
ДанныеЗаказа.Вставить("drink_name", Сервис.ТипСтрока("Водочка", "Название напитка"));
ДанныеЗаказа.Вставить("count"     , Сервис.ТипЧисло(5, "Количество шотов"));
ДанныеЗаказа.Вставить("price"     , Сервис.ТипЧисло(120.40, "Цена"));
ДанныеЗаказа.Вставить("sum"       , Сервис.ТипЧисло(602, "Сумма заказа"));

// Добавляем варианты ответов
Метод.ДобавитьВариантОтвета(200, "Успешное выполнение").ДобавитьДанные(ДанныеЗаказа);

В конце остается вызвать лишь один метод нашего сервиса и на выходе получить описание в формате JSON

ОписаниеJSON = Сервис.ПолучитьОписаниеOpenAPI();

А можно еще проще?

Можно не использовать расширенные типы, код станет проще, но тогда придется отказаться от схем данных и у полей не будет описания.

Сервис.ИспользоватьСхемыДанных = Ложь;

// Описываем структуру возвращаемых данных
ДанныеЗаказа = Новый Структура();
ДанныеЗаказа.Вставить("drink_name", "Водочка");
ДанныеЗаказа.Вставить("count"     , 5);
ДанныеЗаказа.Вставить("price"     , 120.40);
ДанныеЗаказа.Вставить("sum"       , 602);
Ответ = Сервис.ПреобразоватьТипы1СВРасширенныеТипы(ДанныеЗаказа);

// Добавляем варианты ответов
Метод.ДобавитьВариантОтвета(200, "Успешное выполнение").ДобавитьДанные(Ответ);

Зато при таком подходе ответ можно брать из реальной функции, получающей данные для http-сервиса.

Сервис.ИспользоватьСхемыДанных = Ложь;

// Описываем структуру возвращаемых данных
ДанныеЗаказа = БухаринСервисы.ПолучитьДанныеЗаказа(Запрос);
Ответ = Сервис.ПреобразоватьТипы1СВРасширенныеТипы(ДанныеЗаказа);

// Добавляем варианты ответов
Метод.ДобавитьВариантОтвета(200, "Успешное выполнение").ДобавитьДанные(Ответ);

А если еще проще?

Можно не добавлять вручную каждый шаблон и каждый метод. Библиотека умеет загружать структуру http-сервисов из конфигурации, после чего остается только добавить данные в методы.

// Получаем все сервисы из конфигурации
Сервис.ЗагрузитьСервисыИзКонфигурации();
Метод = Сервис.ПолучитьМетод("Бар", "ЗаказатьШот", "POST");
Метод.ДобавитьВариантОтвета(200, "Успешное выполнение").ДобавитьДанные(Ответ);

// Загружаем только определенные http-сервисы
ПараметрыЗагрузки = Сервис.ПараметрыЗагрузкиСервисовИзКонфигурации();
ПараметрыЗагрузки.ВключатьСервисы.Добавить("Бар");
Сервис.ЗагрузитьСервисыИзКонфигурации(ПараметрыЗагрузки);

Как подключить?

Добавляете расширение в конфигурацию, снимаете Безопасный режим, добавляете пользователю роль OpenAPI и пользуетесь.

В расширение встроена обработка для демонстрации возможностей, имеющая Swagger Editor прямо на борту.

В обработке и общем модуле oapi_Документация можно "пощупать" демонстрационные примеры.

А можно сразу начать писать документацию к своим сервисам с помощью встроенного редактора.

Да что там писать, можно сразу и тестировать тут же

Ну или просто любоваться полученым JSON

Что с этим делать потом?

Тут есть несколько вариантов:

• Делаем http-сервис, который отдает нам JSON. Снаружи дергаем сервис, и полученный файл прокидываем внутрь Docker. Радуемся сами или радуем потребителя(ей) нашего API
• Делаем общий модуль, который формирует файлы для всех потребителей наших API, загружаем файлы на какой-нибудь общедоступный ресурс и скидываем потребителю ссылку вида https://editor.swagger.io/?url=https://example.com/api.json

Тестировалось в следующих условиях:

ОС Windows 10 x64, релизы платформы 8.3.17.1386, 8.3.18.891, 8.3.20.1838. Swagger Editor и консоль кода на linux, возможно, заработают, но нужен напильник.

Особенности:

• Поддерживается версия Open API 3.0.3, но не в полном объеме. Например, в спецификацию не вставляются контакты и ссылки на внешние документы
• Авторизация поддерживается только Basic Access
• По некоторым причинам у расширения указан режим совместимости 8.3.10