Tech Blog

Today I setup the first version of a RAPIDoc, a Rest API Rails Documentation Generator and we decided to open source this thing, from now on let’s call it RAPIDoc. It is a API code generator for Rails, describing your Rest resources. We we’re looking for a way to fully integrate documentation of our API into the code base, like Rdoc does. Rdoc didn’t suit our needs, cause it has got nothing to do with Rest and resource stuff, so we decided to hack something together and gave it a name: RAPIDoc.

What does it do?
It generates a API controller containing documenation maked up in a special language. It parses controllers you specify, and generates a ApiController with appropriate views for it. This makes it very easy to document a Rest API. For methods you use, and according to ERB templates you specify it generates the views for you. It doesn’t parse your routes.rb, it was not needed for us, but may be a nice extension for it.

Well how is that RAPI doc looking? Put this in front of a Restful method.

1
2
3
4
5
6
7
8
9
10
11

=begin rapidoc
url:: /projects
method:: GET
access:: FREE
return:: [JSON|XML] - some project
param:: page:int - the page
param:: per_page:int - max items per page
 
Get a list of projects. This method uses pagination. If you want to retreive project 1-10 for example:
/projects?page=1&per_page=10.
=end

For each resource you specify, a view is created and it is put into the index.

Opensource
It is available from now on on:

http://code.google.com/p/rapidoc/

If you find it useful and you want to change some things, become a submitter. Ow yeah, just a note: really experimental code

Tags: documentation, generator, rails, rapidoc