Rails API Doc Generator

RESTTful API documentation generator for Rails. It supports Rails 2.1 and greater. It generates a set of HTML views in the public directory. Parses the desired controllers and generates appropriate views.

Currently does not read routes.rb and requires manual entry of routes

Installation

gem install rapi_doc

Usage

Run rake rapi_doc:setup to generate default Haml template files along with default styles. These files are in <application folder>/config/rapi_doc folder.

Then invoke the generation by calling:

rake rapi_doc:generate

It will analyze the routes.rb files and find the controller files in app/controllers directory that may have the annotation. Only controllers actions with annotation will be parsed and generated the HTML output using the template files and styles in the config/rapi_doc folder. The final result is placed in public/apidoc/.

rake rapi_doc:generate confirmation=true

This rake task is the same as rake rapi_doc:generate but it will acquire your confirmation to generate API doc for each controller.

rake rapi_doc:clean

This rake task will remove the documentation thus generated.

rake rapi_doc:distclean

This rake task will remove the documentation and also the Haml template files and styles created by the rake rapi_doc:setup

Markup Reference

Controller methods and controllers themselves are documented by annotating them with "method markers" and "resource markers" enclosed in "apidoc" comments, similar to that in RDoc.

# =begin apidoc ... method markers # =end

A] Method markers

Method markers are specified like this:

# <<method-marker-name>:: <method-marker-value>

All method markers are optional.

# method: HTTP request type such as GET or POST
# access: access restrictions such as FREE, RESTRICTED for paid subscribers, etc
# return: list of return data-formats like [JSON|XML] and what the return data means
# param: name and type of the parameter expected
# output: output format like JSON, XML. It is recommended that it should include an example of such data.
#         Each output marker must end with ::output-end:: on a separate line.
# request: a request generating code example
# response: a response processing code example

You can define your own custom method markers as well. They will be available as the instance variables against which the _resource_method.html.erb template will be evaluated.

Any other information that needs to be shown in the view can be specified in the apidoc comments as well. It will be shown under the "Description" section for the method in the view.

B] Resource markers

A resource, which is normally a controller object, can also be annotated with apidoc comments.

Method markers are specified the same way as the method markers:

# <<method-marker-name>:: <method-marker-value>
# 
# xml: xml representation of the resource
# json: json representation

Just like in method marker, any other information that needs to be shown in the view can be specified in the apidoc comments as well. It will be shown under the "Description" section for the method in the view.

C] Documentation Example

# =begin apidoc
# url:: /books
# method:: GET
# access:: FREE
# return:: [JSON|XML] - list of book objects
# param:: page:int - the page, default is 1
# param:: per_page:int - max items per page, default is 10
#
# output:: json
# [
#   { "created_at":"2011-12-05T09:46:11Z",
#     "description":"As with the last several books in the series, V Is for Vengeance was a long time in the making.",
#     "id":1,
#     "price":19,
#     "title":"V is for Vengeance",
#     "updated_at":"2011-12-05T09:46:11Z" },
# ]
# ::output-end::
#
# output:: xml
# <books type="array">
#   <book>
#     <id type="integer">1</id>
#     <title>V is for Vengeance</title>
#     <description>As with the last several books in the series, V Is for Vengeance was a long time in the making.</description>
#     <price type="integer">19</price>
#     <created-at type="datetime">2011-12-05T09:46:11Z</created-at>
#     <updated-at type="datetime">2011-12-05T09:46:11Z</updated-at>
#   </book>
# </books>
#::output-end::
#
# Get a list of all books in the system with pagination.  Defaults to 10 per page
# =end

Haml Templates and styles

Resource and resource method annotations are available as instance and local variables in Haml templates. Here are the listing of variables available. But the best way to understand it is to look at the default Haml templates generated by rake rapi_doc:setup in config/rapi_doc folder.

A] Resource Method

@resource_name: Resource name
@method_order: the numerical order of the method
@content: All Misc info
@url: url
@access: public/privileged, etc
@return: the data format of the info
@params: params expected by this api
@outputs: array of [output_format, output example], for example, [json, ....json output.. ]
@request: example of the data expected
@response: example of the response

B] Resource

@name: name
@xml: xml representation of the resource
@json: json representation
@function_blocks: Array of resource method objects described above


Following instance variables are only available in the index template described below (and not in the resource Haml template)
@resource_methods: Array of HTML generated for each of the methods. 
@resource_header: HTML generated for the resource

C] Index

resource_docs: all the resource objects, whose instance variables are described above.
As mentioned before, for each resource, the HTML generated for the resource itself is available in @resource_header
and HTML generated for each of its methods is available in @resource_methods array.

D] Documentaton Output

Documentation generated is located in public/apidoc directory.

index.html: contains the HTML 
styles.css: CSS styles
scripts.js: contains the script used to search within the documentation.

Credit