Maintainer APIs.guru, co-chair W3C WebAPI Discovery Group
Something a little different for this blog; a comparison of four tools which aim to do a similar job, to convert OpenApi / Swagger definitions into simple markdown which can be rendered by Slate (or one of its ports). Slate itself and its alternative implementations / ports will likely be the subject of a follow-up post on this blog.
Disclaimer: the author of this blog post is also the author of one of the tools compared (
widdershins), and shins, the Node.js port of Slate used here to convert each tool's Slate markdown into HTML.
When I started
widdershins I could not find any tools to directly convert OpenAPI / Swagger definitions to Slate, except for
swagger2slate which is written in PHP and was at the time in an unmaintained state. Some weeks later on and two more tools, developed in Node.js (like
widdershins) have appeared, and
swagger2slate has seen further development, hence this comparison.
shins uses the common-mark compatible markdown-it as its markdown processor, there may be differences in the rendered HTML compared to that produced by
redcarpet, the markdown library used by Ruby Slate.
Each tool may be optimised for a particular Slate CSS theme. This is not taken into account here, but where an example site is provided, it is linked to below.
Only the example
petstore.json has been used so far to compare each tool, which may not demonstrate all features to best effect.
If you use Java and/or Swagger-CodeGen, two other projects which have been brought to my attention may be worth looking at:
First up is:
openapi2slate is a BSD-licensed Node.js-based tool developed by Scrive which describes itself as
An opinionated (and work in progress) converter from OpenAPI to Slate markdown
openapi2slatecertainly looks impressive with Scrive's CSS theming, as can be seen on their API documentation
openapi2slatecan use OpenAPI vendor extensions to mark tags and parameters as internal use only, making it simple to produce both internal and external-facing documentation from the same OpenAPI definition.
undefinedin the table-of-contents footer.
shinsat least rendering it sub-optimally. This can be seen in unconverted headings. This may be due to an amount of HTML which
openapi2slatemixes in with the markdown.
As documented in the project's README,
openapi2slate has a few limitations / design decisions to be aware of:
Dereferncing(sic) is not properly implemented, instead it tries to dereference the file for you and use that. YMMV.
API Schema works fairly OK, some features may be missing...
We render things in Slate Markdown that fits our needs and customisations, so this may not work well for you!
Swagger-to-Slate is also a Node.js-based tool, under the MIT license, developed by Lav Kumar Vishwakarma, which describes itself as
Node module which converts the swagger.json or YAML file into slate markdown
swagger-to-slateuppercases the table-of-contents, making it look somewhat shouty
shellis defined as a language tab, no examples are shown yet
codeblocks not rendering
Swagger-to-Slate includes Slate's
_error.md file by default, so you need to remember to update this to include your API documentation.
Swagger2Slate is in some way the granddaddy of all these tools, predating them by about 18-months.
It is written as a PHP application by Andrey Putilov and the project description is
I wasn't originally going to include
Swagger2Slate in this comparison, because by the author's own admission it was no-longer maintained, had several outstanding issues, and being written in PHP wasn't something that was immediately easy for me to test (much like Slate, being written in Ruby - and not supporting Windows, which may be the reason a number of
Node.js-based ports exist).
However, as of this writing, the latest commit to
Swagger2Slate was only five hours ago, and deploying a slightly hacked version of the code to heroku allowed me to see the example output.
Object, and are hyperlinks
Swagger2Slatehappily works on any OpenAPI definition, no matter how it is generated.
Widdershins is written by the author of this blog post, and the author of
shins, so you might want to stop reading here!
producesMIME-types are detected
Widdershinsuses operationIds if available for the table-of-contents. This may not be optimal for human-readable documentation
Widdershinsis in hindsight not the most descriptive name, and might imply it only works with
shins. This is not the case,
Widdershinsshould work with the original Ruby
Slateor any of its ports / forks / derivatives.
Object, not the model names