Over a million developers have joined DZone.

Converting OpenAPI Spec to Slate and Shins

DZone's Guide to

Converting OpenAPI Spec to Slate and Shins

Kin Lane believes that a diverse range of approaches is optimal, but only as long as we do not lose our machine-readable core.

· Integration Zone
Free Resource

Learn how API management supports better integration in Achieving Enterprise Agility with Microservices and API Management, brought to you in partnership with 3scale

Someone turned me on to an OpenAPI Spec to Slate and 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 a 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.

The OpenAPI Spec to markdown converter also introduced me to a version of Slate that is ported to JavaScript and Node.js called Shins. I'm going to add Shins to my API documentation research, and "widdershins" the OpenAPI Spec to markdown converter to my API definition research. The auto-generation of attractive API documentation like Slate and Shins seems like a valid approach to getting things done and worth including in my research.

I am increasingly publishing YAML editions of my OpenAPI Specs that 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 is optimal as long as we do not lose our machine-readable core.

Unleash the power of your APIs with future-proof API management - Create your account and start your free trial today, brought to you in partnership with 3scale.

api ,integration ,slate ,shins

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.


Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.


{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}