Комментарии 6
А вот третьего, на мой взгляд, не дано.
Мне кажется третий вариант это генерировать документацию гибридно.
Генерировать документацию из компонентов для фронта. Достаточно в базовом компоненте проверять добавленные в свойста новые, уникальные методы.
Генерировать документацию бэкенда из свагера.
А в тестах оставить пользовательские кейсы, проверки приложения mocha на фронте ( они же документация) и на бэке не знаю, свой тоже фреймфорк есть для тестов.
Так появляются разные разделы документации и каждый из разделов не перегружен логикой формирования
В мире микросервисов только метрики трейсинг и логирование помогут разобраться что с чем связано)
swagger выдает набора параметров сервиса и не даёт понимания о его бизнес-составляющей: ни о его назначении , ни о взаимосвязи с другими сервисами, ни о особенностях логики его работы.
yaml- формально там можно описать набор разворачиваемых компонентов, порты, адреса хостов и даже ролевую модель, но , опять-же бизнесовую составляющую мы опускаем+ члены команды должны понимать формат и совместно его редактировать и поддерживать в т.ч. покрытием тестами.
Любая ошибка в описании и у тебя какая-то железка потеряла доступ, либо модуль/библиотека не погрузилась, контейнер не развернулся - да и вообще что угодно может произойти и ты засучив рукава, вооружившись кувалдой и серпом идёшь искать и разбираться что там сломалось. Отсюда жёсткие требования к пониманию формата всей командой и контролю версий. Как автор предлагает решать эту проблему?
давайте по порядку ) у swagger'а изначально и нет такой цели — он про контракт, а не про его использование. Использование и взаимосвязи — это как раз к архитектуре (про это пишу в приведенной выше ссылкой статье).
В yaml'ах бизнес-составляющую тоже, естественно, размещать не стоит, хотя там уже могут быть как раз связи с другими сервисами (разрешённые исходящие REST-вызовы, подписки на очереди и т.д.).
В качестве всегда актуальной документации бизнес-логики могу посоветовать BPMN-схемы и движки их исполняющие. Мы используем, например, Camunda.
Но в целом, вопрос описания назначения сервисов и т.д. автодокументацией или тестами не закрыт — согласен, рассуждаю об этом в приведенном выше докладе (часть про автогенерацию архитектуры), или в отдельном более коротком: https://www.youtube.com/watch?v=fb2UjqjHGUE
Если интересно — можно ознакомиться.
А вот про любую ошибку в описании — если выполнить мои рекомендации по архитектуре и инфре as Code и связыванию их тестами, то ошибка отловится автоматически (несоответствие yaml'а архитектурной схеме к примеру) и тест сразу покажет в каком файле и какая допущена неточность. Тот же тест в другом случае скажет, что наоборот — в yaml'е мы изменения внесли, а вот в схемку — забыли.
Ну и помимо тестов естественно должен быть ещё мониторинг как на уровне успешности CI/CD процессов, так и реалтайм эксплуатации
Поддержка актуальности документации и неодназначность термина «as Code»