One of the most important parts of our product is the API explorer, which lets for users of your documentation try out your APIs from within a web browser. To enable this feature, you have to tell us about the format of your APIs: base urls, path parameters, body parameters, headers, authentication, etc. You can either enter these in manually, or upload your Swagger 2.0 spec to us — more about OAS support later. Once you've done this, we display form inputs, along with some dynamically updated code samples, that can be copy and pasted into an editor and run in a variety of languages.
Current setup
Our current API Explorer has served us well for the most basic of use cases: top level JSON encoded body parameters, path parameters containing API version numbers, and authentication headers that take API keys. However, it has failed us for more complex cases.
- Deeply nested object structures
These are not supported: we only traverse one level deep. - Multiple authentication schemes
This may or may not work depending on what you're attempting to do. - APIs with hundreds of endpoints
Due to the way we were rendering, we had some extremely slow pages.
It was clear to us — and our customers having issues with the non-basic use cases — that we had to do better. Our current API explorer is a mixture of server-rendered jade pug templates and Angular 1.3. Not that those things are inherently bad, but features have been bolted on over the years with minimal automated tests. This led to us causing unnecessary regressions for some of our clients, breaking things that used to work and only finding out about it when someone complains — not good!
Rewriting
When OAS 3 was released in July of last year, we thought that it may be a good time to rewrite our explorer to support it, while also solving some of the other issues that we had.
Without further ado, here's our new shiny API Explorer. At the top of that page we have a dropdown containing a list of all APIs in the OpenAPI Directory for testing. You can also provide your Swagger/OAS file to it via the ?selected=<url to oas file> query string. This will fetch your Swagger 2 file, convert it to OAS 3 (using the excellent swagger2openapi) and render it.
This has also been merged into ReadMe, and is behind a flag while we iron out the final issues. If you'd like to test it out, you can temporarily turn on the flag using the ?newApiExplorer=true query string on your reference page like so: https://pet-store-api-explorer.readme.io/v1.0/reference?newApiExplorer=true. This will only affect this page.
This has the following improvements over our existing explorer:
- Instant code samples, rendered client side as opposed to having to make an AJAX call to render them (using
httpsnippet). - Authentication headers now included in code samples — they used to only be applied when the request was made.
- Better support for nested objects and JSON Schema (using react-jsonschema-form).
- Lazy rendering of endpoints to help with the speed of initial render (using react-waypoint).
There are going to be issues with it, including some inconsistencies with our existing explorer. Some known issues that we're working on include:
- Allowing OAS 3 uploads directly to ReadMe
- Styling of nested objects
- Server rendering
- Heavy page size from using Angular and React on the same page
If you have any issues or want us to help beta testing by getting us to turn it on permanently for your project, please contact support@readme.io. Alternatively you can file issues on the GitHub repo.