Статический swagger.json
к сведению
Эта статья о планируемом функционале. В текущей рабочей версии эти функции пока ещё отсутствуют.
Доводы "за" и "против"
Плюсы
- Описания объектов и методов находятся в том же модуле что и сам код этих методов - модуле HTTP-сервиса. Не требуется разыскивать отдельные общие модули и переключаться между модулями при описании.
- Описание пишется не кодом, а при помощи комментариев. Так что формировать описание может не программист, а кто-то из команды с меньшей квалификацией.
- Описание формируется не динамически, а берётся из заранее скомпилированного файла. Что снижает время открытия описания (особенно для больших API) и снижает нагрузку на сервер 1С: Предприятия.
Минусы
- Требуются дополнительные действия чтобы скомпилировать файл описания и поместить его в рабочую базу. Это возможно автоматизировать во время сборки при помощи скриптов.
- Для создания комментариев с описаниями объектов и методов требуется изучить специализированный формат написания таких комментариев. В принципе, он не сильно сложен, но всё равно требует от создателя описаний определённых усилий по соблюдению формата.