My observation is that nowadays Open API definitions as a source of
documentation get more and more important. We currently use the event store
as part of a research project and want to use the "read" operations as a
kind of "standard" for event stores in general. When I tried to describe
the HTTP API I found that many questions are left open. They are not really
covered in the docs or in the swagger file. I often needed to execute the
function on a running event store to figure out how it actually works.
Im general I like the way you document the event store with DocFX, but an
Open API description is much more precise. Things like possible header
fields or what fields are exactly available in the response when reading an
event from a stream are not very well documented.
- Doc: "The non-atom version of the event has fewer details about the
event." - But which fields exactly are available with what "Accept" header?
- Doc: "you receive a standard AtomFeed document as a response" - If you
look at the XML AtomFeed specification you wil see that there are several
options (for example "attributes") that cannot be represented in JSON and
it's therefore not clear how they are returned in a JSON response. This not
documented anywhere (or at least I could find information about
the "vnd.eventstore.atom+json" format).
With "API first" we could start out and simply work together on the API
file(s). This would allow to enhance the exact API definition step-by-step
without needing to dig into the C# code base. Of course there is a cost
associated: It's necessary to ensure somehow that the implementation is
compliant with the API (Unit tests?). Another benefit of "API first" would
be that you can easily generate mocks or client libraries from the Open API