On AGL side, we have the following requirements about API description (non exhaustive list):

• the API specification may be defined by one person
• then it can be implemented and amended by another person [the developer]
• some other people from QA would also leverage the API description to write/execute some
  automated tests (test the verbs calls with good values, bad values etc. and
  check the results)
• some technical information could also be used at runtime (APIs dependencies for example)
• and at the end, we want also everybody to be able to document the API in the same
  file. Typically, we expect a description of each API verb with its parameters,
  and the detailed description of the responses (fields, meaning, error cases etc.)

Some background info on the topic:
https://fr.slideshare.net/tedepstein/openapid-vnext-openapi-vnext-events-alternative-schemas-the-road-ahead
The beginning of the presentation shows the history for specifying (web)
APIs. It started by WSDL, then RAML appeared, then Swagger, openAPI etc.

One special thing about the APIs in AGL: the bindings are independent of the
transport mechanism (handled by the binder). So sending a request is just
sending a json object over the wire and get a json result back (whatever the
wire is).

On the other hand, most of the formats we found until recently are related to REST APIs, used
on the web and don't exactly match what we do with bindings: the APIs
description are not independent of the transport. Even openAPI 3.0 which handles
"server messages" (=messages pushed from a webserver to a client through a
websocket) doesn't represent exactly what we do with events in bindings.

We also discovered the emerging specification AsyncAPI 1.2 which is more focused
on messages and doesn't care about the transport. So it's closer to what we do
in AGL but this deserves more investigation to see if it can be used or not.

As a summary, we have at least 2 modern specifications to investigate deeper: openAPI and
asyncAPI.

Links:

• openAPI 3.0 : https://www.openapis.org/
• asyncAPI 1.2 : https://www.asyncapi.com/

Some background articles on asyncAPI:

• https://nordicapis.com/tooling-review-asyncapi/
• https://streamdata.io/blog/streamdataio-api-openapi-asyncapi/

Sample generated docsite:
https://mermade.github.io/shins/asyncapi.html#asyncapi-sample-v1-0-0