SwaggerUI-like application for documenting events

EventStoreDB
#1

Hi,

We are just getting started with Event Driven Architectures where I am and folk are asking about how to document the events and their schema.

In the request/response space the SwaggerUI [1] project can be used for auto-generating route and schema documentation which you can annotate.

Has anyone had any success documenting their JSON objects while using EventStore? I’m thinking a human readable list of Stream->EventType->Doc/Schema.

Or are their alternatives to using a tool here? Can people make do just by looking at real event examples?

Thanks,

Joe Wright.

[1] http://swagger.io/swagger-ui/

#2

Doing it from EventStore seems backwards, since it’s schemaless, it implies you’ve already stored one of each events. If you’re in a typed language I think it would be easier to just reflect over your events and produce required documentation.

/Peter

#3

Did you find a solution?

I am also looking for such a documentation tool.

It seems strange, that there is no good answer from EventStore, as every user of EventStore should run into this.

Best, Tim

#4

We explored a bit using protobuf. They have code generation to many languages and it can help to statically check that everything is correct between projects.

We are planning in using them. For us they supply everything we need.

For docs with protobuf you can use things like https://github.com/pseudomuto/protoc-gen-doc

Bests!

#5

We decided to follow this approach:
http://progressivecoder.com/implementing-event-sourcing-with-axon-and-spring-boot-part-3/

“Step 4 - Listing the Events” describes a query for events:

GET /…/events

We use Swagger to define this query and its response, which is an array, where each item is oneOf the domain events.

Currently, we use this approach just for documentation. We don’t yet have an implemtation of the query.

#6

Hey all, I’m to completely sure if I’m following the conversation here correctly, but we have a swagger file here - https://github.com/EventStore/documentation/blob/master/http-api/swagger.json

That generates the docs here - https://eventstore.org/docs/http-api/swagger.html

Chris

#7

Most of my events implement some kind of interface - different contexts probably slightly differ.
V easy to reflect over assemblies to find them.

But really I use things like event modelling and event storming to model systems before I start - that tends to give this stuff. Careless event modelling leads to lots of code fluff and complexity later.

You can test drive these systems easily - but it’s faster to drive examples through customer and then test drive their implementation - IE when not spiking then events decided before code or at least in a non code context

Another way is to list the apply functions in an aggregate from when it reloads from a stream. That would be my goto tbh.

At the extremity (IE where swagger lives) are you not dealing with commands? These probably exposed via a standard controller and get mapped internally to a command via some kind app service?

If you wanted to map an unknown system you could subscribe to all and then build a graph of category -> event type -> fields etc.