OpenAPI generators for documentation and testing the API

[mattheworiordan]

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/)

Documenting the API

• 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

Testing the API

• Swagger UI: https://swagger.io/tools/swagger-ui/
• Postman: try out https://app.getpostman.com/run-collection/d27522fdf8bef020617b

Other

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

[mattheworiordan]

@tomczoink what's the status on this work?