Inevitably, during our first discussion with prospective clients about documenting an API, we are asked if we can do “something like Stripe’s”. Unfortunately, until recently, our response was “not really” because Stripe had created its own tool to publish API documentation.
Now, thanks to the hard work that people have put into open source projects like Redoc and the Open API Specification, we can finally say “Yes” to these requests for API documentation. Previously, three-column, responsive, web-based documentation was only available as part of an expensive subscription to a development platform or as a customer-developed portal, but as REST APIs have become more and more popular, the tools to support their development and use have become more widespread. We can provide three-column API specifications with a basic quick start guide hosted on our client’s own website. For the client, that means no recurring fees and no commitment to a development pipeline that may not be a good fit for its company.
For many of our clients, we are able to use their existing API documentation (with some editing), translate it into the Open API specification, and add any additional content (for example, how to build a basic application). At that point, using Redoc, it’s a simple matter of generating a website that looks something like this:
With this three-column format that organizes navigation, technical specifications, and examples, it’s easy for developers to find and understand the features of your API. And, as we all know, “easy” often means they, the developers, are more likely to use your API over one that isn’t. Clearly, as they say in corporate parlance, a “win-win”.