SWEET - Swagger для 1С. Инструмент для генерации OpenApi спецификаций

Область применения

С увеличением числа интеграций возникает необходимость в документировании HTTP-сервисов.
В настоящее время Swagger и спецификации OpenAPI представляют собой стандарт для документирования REST API.

Были выработаны следующие предпочтения к инструменту:

1. У разработчиков имеется множество задач, при этом недостаток времени на изучение структуры спецификации и правил её заполнения существенно затрудняет процесс работы.
   Необходим инструмент, который минимизирует нагрузку на разработчиков, позволяя избежать необходимости изучения новой информации и написания дополнительного кода. 
2. Учитывая высокую стоимость рабочего времени разработчиков, требуется решение, которое обеспечит быстрое описание существующих HTTP-сервисов и в дальнейшем упростит создание и поддержку новых сервисов. 
3. Инструмент должен одинаково хорошо работать как с проектами EDT, так и с файлами, выгруженными из конфигуратора.
4. Решение должно быть удобным, безопасным, работать без доступа в Internet и без установки стороннего ПО.
5. Инструмент должен быть мультиплатформенным.

Все эти требования выполняет SWEET© (Swagger Easy Editing Tool).

Технические особенности

Инструмент использован на различных конфигурациях, от самописных, до последних релизов 1С:БП 3.0, 1C:ЗУП 3.1 и 1C:ERP Управление предприятием 2.0.
Инструмент разрабатывался в течение года, постоянно дорабатывался с учетом пожеланий разработчиков, которые его использовали.

Код закрыт.

Функциональные возможности

Решение состоит из:

1. Документирующий комментарий - описание спецификации формируется на основании комментариев к функциям-обработчикам HTTP-запросов. Разработанный синтаксис и структура комментария приближены к стандартам 1С, насколько это было возможно. Подробное описание синтаксиса и примеры представлены по ссылке на GitHub.

2. Онлайн-редактор - полноценный редактор кода, с автозаменой и подсвечиванием ошибок для быстрого и безошибочного написания документирующего комментария.

Принцип работы:

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

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

Пример результата работы консольного приложения:

Документация с описанием возможностей и примерами доступна на GitHub

Достоинства

• Наглядность

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

• Скорость

Быстрое создание и поддержка документирующего комментария при помощи онлайн-редактора

• Вариативность

Работает как с файлами проекта EDT, так и с файлами конфигурации, выгруженных из конфигуратора

• Минимальность

Не требует установки стороннего ПО. Можно использовать на серверах с минимальным набором ПО, без доступа в Internet

• Доступность

Консольный и десктопный вариант приложения доступны для Windows, Linux и MacOs

Видеодемонстрация

Техническая поддержка и обновления

Бесплатный период техподдержки составляет 1 месяц со дня покупки.

Также после приобретения Вы получаете 12 месяцев бесплатных обновлений.

По окончании бесплатного периода вы можете приобрести услугу технической поддержки с доступом к обновлениям на платной основе.

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

Задать вопрос по программе можно по кнопке "Техподдержка" на странице описания.

При создании тикета необходимо предоставить:

1. Номер заказа
2. Описание вопроса. Если это ошибки - напишите порядок ваших действий с программой, которые к ней привели (приложите видео/скриншоты/отчеты об ошибке)
3. Точную конфигурацию 1С, и версию платформы, на которой используете купленное решение (наименование и версию 1С можно взять из раздела "О программе"), версию купленной программы.

К созданной заявке подключается специалист. Дальнейшее обсуждение проблемы будет проходить в тикете техподдержки. Стандартный срок реакции - 24 часа в рабочие дни с момента обращения

Внимание! Техническая поддержка предоставляется исключительно в рамках переписки по обращению. В некоторых случаях для диагностики ошибок и/или вопросов, связанных с особенностями использования продукта в информационных базах покупателя, может потребоваться дополнительная платная диагностика с организацией удаленного доступа к информационной базе. Стоимость уточняется индивидуально.
 

Техподдержка