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

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

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

Для HTTP я использую OpenAPI.

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

Каковы передовые методы создания такого рода документации?


architecture documentation event-driven-design
person Victor    schedule 08.06.2018    source источник

Ответы (1)


arrow_upward
6
arrow_downward

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

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

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

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

person Aleksi    schedule 29.08.2019
comment
Два отличных инструмента! Это инструменты, которые я искал. На тот момент мы не решали проблему, все общение и события документировались с помощью вики-страниц. - person Victor; 29.08.2019