Research alternatives to Swagger UI

[bajiat]

The current Swagger UI implementation is causing strange behavior. Look for alternatives to using the Swagger UI in iFrame. Document the alternatives.

Study the Swagger UI features and document them. For each feature, look for potential alternatives and document them.

Swagger UI provides at least the following features:

• documentation viewer - render a Swagger file with a pleasing user interface
• API console - make calls directly to the API from the docs
• validation - check that a given swagger file is valid

We need to determine the priority of each of these features, and what tool(s) will provide similar functionality.

Possible alternatives

ReDoc

ReDoc is a Swagger documentation viewer, inspired by the Stripe API docs. ReDoc supports at least the following feature(s):

• documentation viewer

[brylie]

It has been really hard to integrate Swagger UI into our documentation page. We have resorted to using an iframe, rather than the simple JavaScript call from the Swagger UI documentation. The upstream support request does not seem to have any traction, unless we fix this and submit a pull request.

[brylie]

For now we have decided to continue using Swagger UI. At some later point, we may again consider switching to ReDoc.