Документирование событийно-управляемой архитектуры

Question

Я проектирую управляемую событиями систему, которая будет построена по крайней мере двумя командами с двумя различными аутсорсинговыми компаниями.

Мы все спроектировали внутренне, но сейчас я создаю документацию для команды разработчиков.

Для HTTP, который я использую OpenAPI .

Есть ли какой-либо инструмент или язык для описания событий и потоков обработки?

Что такоехорошие практики для создания такого рода документации?

Answer 1

Вот один из подходов:

1. Определение окончательного списка событий, которые принимает система.События могут основываться, например, на спецификации CloudEvents и документироваться в JSONSchema (согласно этому ответу ).
2. Для каждого компонента системы определить, какие события(из вышеупомянутого списка) компонент производит и потребляет.
3. Для особенно волосатых отдельных потоков событий запишите их в диаграммах последовательности.

Спецификация AsyncAPI другой интересный (и более всеобъемлющий) подход.Это немного похоже на Swagger / OpenAPI, но для систем, управляемых событиями: вместо путей и операций HTTP вы определяете каналы обмена сообщениями и операции подписки / публикации.

Немного поздний ответ, мне было бы интересно услышать, как вы решили проблему!