На Инфостарте хватает публикаций на тему Swagger и 1C. Долгое время я пользовался Swagger для 1С и даже дорабатывал формат комментариев и парсер под свои нужды. Инструмент отличный, но гибкости не хватало.
В итоге родилась небольшая библиотека, которая позволяет программисту описать документацию буквально в несколько строк. Хотя вру, строк может быть довольно много, но пишется такая документация быстро.
Как это работает?
Главным объектом библиотеки является Сервис, который может включать в себя любое количество шаблонов 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
Связанные публикации:
- Swagger для 1С
- HTTP сервисы по OpenAPI спецификациям
- Swagger для 1С. Описание сложной структуры входящих и исходящих данных
- Анализ HTTP API, документирование в OpenAPI и переиспользование в Postman
Исходники:
Исходники можно взять тут https://github.com/salexdv/swagger_1c
