Updated & enhanced Open API V3 YAML definition

EventStoreDB
#1

Hi there,

Is there an up-to-date Open API V3 definition available?

I only found this V2 Swagger JSON definition:

https://github.com/EventStore/documentation/blob/master/http-api/swagger.json

How about an updated and more complete Open API V3 YAML version?

There seems to be some information missing (like a description of the JSON Atom Feed implementation “vnd.eventstore.atom+json”).

Also some descriptions are not really self-explaining and could be improved.

If there is interest in this topic, I could start some cleanup and enhancement of the API doc.

Cheers,

Michael

#2

Hey Michael.

Sadly DocFX doesn’t yet support v3 yet, so we’re stuck on v2 until they do. It’s top of my todo list once it’s possible.

Chris

#3

Ah, OK. So you follow a "code first" approach.

Mybe it makes sense to switch to "API first" here and maintain the Open API
YAML file as primary source?

#4

Well, two things here…

1. DocFX renders the file as more human readable documentation, and renders the rest of the docs, so that’s fiddly to do much about. And you’re the first I’ve known who’s even found and read the raw swagger file.
2. I can’t make any comments on coding decisions, I’m just working on docs. That would sure be a great thing to do for me too. I’ve even mentioned annotations in the code in the past to generate the file, but I think there are higher priorities. Maybe one day, who knows.

Danke sehr, Chris

#5

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.

Examples:

   - 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
definition.