When working on an API, everyone wants documentation and nobody wants to take the time to write it. It's often tedious work that often doesn't directly benefit anyone but the developer.

In this series of blog posts, I'll attempt at starting a project to generate API docs for one of the open source options such as slate or swagger.io.

The reason for this is simply that I've been unable to find anything that does anything like this. For most API's it would not be feasible to generate documentation based on the code.

Ruby on Rails + JSON API

The API docs will be generated based on the code that is written for Ruby on Rails for JSON API . Since JSON API has a very predictable structure, methods and limitations I think it might be possible (With some work) to get this done. Any other language I'm not so sure about if this could work as well.

It looks like Slate is mostly markdown which will be quite the effort to generate, but looks by far the nicest to me. Swagger.io on the other hand seems to have an easier format to create, but the style doesn't appeal to me.

For now I'll start with swagger, since that is the most easy to test in their editor. If it works well I might move it over to slate. We'll see what happens.