OpenAPI generators for documentation and testing the API

The OpenAPI specification really opens up a lot of opportunities that need some further exploring.

At a high level, we should:

Ensure our OpenAPI spec accurately reflects our current REST API for the realtime service
Later we can consider extending this to our new provisioning API
Start defining AsyncAPI specs for our endpoints that support open protocols
Extend both of these to the Hub and API Streamer so that specs are auto-generated for customers, consumers can use these specs to explore and consume APIs using open protocols, and we can contribute back to AsyncAPI potentially as we use it more
Generate documentation from the specs
Allow testing of the APIs from the specs

Some related projects (some of these come from https://openapi.tools/)

Postman can generate very nice docs immediately: https://documenter.getpostman.com/view/7798459/S1TbSuhB?version=latest#9995174e-af4a-46ac-a887-baa3eaead67e. Shortcoming is probably how much we can customise this, not open source as far as I can tell, and has no testing capabilities without the native Postman app.
Redoc: https://github.com/Redocly/redoc and demo at https://redocly.github.io/redoc, nice, no support for AsyncAPI or testing console.
Lucybot: https://lucybot.com/docgen, includes dev console as far as I can tell, but not simple or the best in terms of UI.
Dapperbox: https://github.com/DapperDox/dapperdox, seems good, but no dev console, no asyncapi
Widdershins: https://github.com/mermade/widdershins, our preference for now, very customisable docs, nice UI, supports async (fledgling). No test console, but we could link off to test consoles perhaps, and with the UI being generated via open source, we could consider a login button in these docs that allows a user to use their API keys automatically. See asyncAPI exmaple https://mermade.github.io/shins/asyncapi.html?go#asyncapi-sample-v1-0-0, OpenAPI example https://mermade.github.io/shins/index.html#swagger-petstore

Insomnia https://insomnia.rest/ is a great OpenAPI development tool, possibly better than postman, but not really relevant to what we're doing sadly given it's not a documenter / runs on the web.

ably / open-specs