Describe WebSockets with AsyncAPI

[dgarcia360]

WebSockets are currently not documented in a formal language, making it difficult to discuss enhancements and share a contract between REST and SDKs.

The AsyncAPI Specification allows describing document message-driven APIs in a machine-readable format in a similar way we are using OpenAPI for REST endpoints.

More info: https://www.asyncapi.com/docs/specifications/2.0.0/

Current WebSockets spec: https://docs.symbolplatform.com/api.html#websockets

[Vektrat]

is it worth it? we have such a little offer of WS interface... and we do have a a formal document description https://docs.symbolplatform.com/api.html#websockets

[fboucquez]

Can this be integrated to open API and the generators? Or just a more formalized documentation? I think it worths having a look.

[dgarcia360]

AsyncAPI cannot be integrated directly into OpenAPI. In fact, the initiative was born because OpenAPI does not support describing message-driven APIs. Public-facing docs can be generated from the definitions with https://github.com/asyncapi/generator

[fboucquez]

If it's not integrated out of the box it doesn't worth having the extra infrastructure to generate the docs and code just for WS.

Updating https://docs.symbolplatform.com/api.html#websockets with the payload wrapper from symbol/catapult-rest#309 would do the trick.