Convert OpenAPI Spec to Slate / Shins Markdown API Docs
17 Oct 2016
Someone turned me on to an OpenAPI Spec to Slate / Shins compatible markdown converter on Github this last week. I have been an advocate for making sure we are still using machine readable API definitions for our API documentation, even if we are deploying the more attractive Slate. I've been encouraging folks to develop an attractive option for API documentation driven by OpenAPI Spec for some time, so I am happy to add this converter to my API documentation research and toolbox.
I am increasingly publishing YAML editions of my OpenAPI Specs which drive API documentation that operates on Jekyll, using Liquid. So I am all about having many different ways to skin the API documentation beast, allowing it to be easily deployed as part of any CI flow, and enabling the publishing of API docs for many different APIs, in many different developer portals or embedded on any device as part of IoT deployments. I think that a diverse range of approaches are optimal, as long as we do not lose our machine readable core.