The land of Shattered dreams

Welcome to the online revolution…

Documenting APIs

| Comments

One of the projects I am working on at work is revamping our mobile applications.

We are designing a RESTful web service layer that a mobile device will use to allow a customer to do various things.

One of the problems I have is that a third party is going to build the service layer and they need to be told what services the API layer has to expose. The mobile devs also need to know what to expect from the service.

I’ve tried to document everything using Word documents, but I couldn’t really get to a format that I liked. After talking to a few people I decided to try a couple of tools


Apiary allows you to define an API using a simple, Markdown inspired DSL.

--- Sample API v2 ---
Welcome to our API. Comments support [Markdown]( syntax.
-- Shopping Cart Resources --
GET /shopping-cart
> Accept: application/json
< 200
< Content-Type: application/json
{ "items": [
    { "url": "/shopping-cart/1", "product":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 }
  ] }

It turns this markdown into some nice looking documentation to describe your API. It even lets you call the API from within Apiary and it can stub your API for you as well…

I liked it, but I couldn’t put the level of detail in the documentation that I wanted. I’d also prefer to deploy the documentation with the API not on Apiary’s site.


Swagger have taken a slightly different approach, or actually several approaches. You can document you api in a number of ways: you can write some json to describe it, you can write java/scala and annotate your code or you can do it in javascript. Either way you end up with a load of json that describes your API.

Swagger-ui can be deployed with the API and renders the json in a nice looking format. You can also use it to call the API, but it doesn’t stub it for you.

You can see a demo here.

In the end I used swagger, and annotated a Javascript stub that I was writing anyway. I can document everything I need to, and the developers get a nice UI to see what the API does.