Documenting an Event-Driven Architecture

Question

I'm designing an Event-Driven system to be built by at least two teams with two different outsourcing companies.

We have designed everything internally, but now I'm creating the documentation for the development team.

For the HTTP I'm using OpenAPI.

Is there any tool or language to describe Events and Streams of processing?

What are the good practices for creating this kind of documentation?

Answer 1

Here's one approach:

1. Define a definitive list of events the system accepts. The events could be based on the CloudEvents spec, for example, and documented in JSONSchema (as per this answer).
2. For each system component, define which events (out of the aforementioned list) the component produces and consumes.
3. For particularly hairy individual event flows write them out in sequence diagrams.

The AsyncAPI spec is another interesting (and more all-encompassing) approach. It's a bit like Swagger/OpenAPI but for event-driven systems: instead of paths and HTTP operations you define messaging channels and subscribe/publish operations.

Bit of a late answer, I'd be curious to hear how you ended up solving the problem!