Какие инструменты использовать при документировании схемы событий

Question

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

Какие общие инструменты используются для этого варианта использования?

Любые ссылки или предложения приветствуются.

Answer 1

Я бы начал с общей спецификации CloudEvents и смоделировал мои события на ее основе, то есть определил события как подтипы общей модели CloudEvent. Преимущество здесь заключается в совместимости с другими системами, основанными на той же спецификации, а также с существующими инструментами, такими как языковые SDK.

Что касается документации, я бы выбрал JSONSchema: вот определение JSONSchema для общего CloudEvent, например.

В качестве альтернативы есть спецификация AsyncAPI, которую вы можете использовать вместо или вместе с CloudEvents: прочитайте здесь о том, как эти два взаимосвязаны.