Originally published at: http://www.sitepoint.com/writing-api-documentation-slate/
So you’ve built yourself an API. Perhaps it’s REST_ful_, REST_like_ or something else entirely. You’ve implemented authentication – be it using OAuth, HTTP Basic Auth or JSON Web Tokens. You’ve fashioned your responses using JSON, maybe XML, or even something else. Your unit and integration tests are passing, you may have a third-party service such a Runscope testing it periodically, or using JSON or XML schemas to validate your responses.
There’s one more thing, however.
There are a number of ways in which you can put together your documentation. For the purposes of this article I’ll assume it’s web-based, whether it’s publicly available over the internet or privately held on a company intranet.
You could of course hand-code it in HTML. You could use a paid service such as Readme.io. There are even tools to help automatically generate API documentation from source-code such as Doxygen and API Blueprint, or for creating dynamic docs; such as Swagger.
Another option is Slate. Slate allows you to write your API documentation by hand using markdown, which it will then package up as a pre-styled static HTML site for you. Because it generates static HTML, hosting is straightforward – in particular, it’s a breeze to host with Github Pages. Let’s take a look at how it works, and go through an example from installation through to deployment.