Document your API with Slate and Docker

Slate is an awesome tool which creates beautiful API documentation from markdown.

However, as someone who doesn't code in Ruby everyday .. I often find the setup a little of a barrier to entry. For some reason .. Ruby doesn't just work for me :^).

Docker to the rescue

This is a perfect fit for our good friend Docker. Tatum (Docker-acquired - soon to be Docker Cloud I do believe) provide a base image we can use: tatum/slate

The instructions on there are for regular Docker. I <3 Docker Compose .. so I'll use that in this example:

Download the slate code:

wget https://github.com/tripit/slate/archive/master.zip  

Extract the source directory to where you want to store you documentation.

From the location where you copied the contents of the source directory. Add the following:

Dockerfile

FROM tutum/slate  

docker-compose.yml

docs:  
  build: .
  ports:
    - "4567:4567"
  volumes:
    - ".:/app/source"  

Some notes:

  • We expose the app on port 4567
  • We mount the current directory in /app/source in the container. This means that we don't have to rebuild the whole image every time we want to apply changes. We can just restart the service.

Run the service

To see it in action:

docker-compose up  

You docs are now available at: http:{docker-machine ip}:4567

When you make changes to your docs, you will need to restart the service in order for those changes to apply:

docker-compose restart  

And that's all there is to it :).

For those in a hurry

Because: ain't nobody got time for that. There's a prepared repo available here. You can just download that:

wget https://github.com/toast38coza/docker-slate/archive/master.zip  

and get going right away by simply running: docker-compose up.