Rest Api Doc

Rest API doc generates an easy way to create a Twitter style document for your RESTful interface

Leveraging Twitter Bootstrap to create an easy to read document for your RESTful api.

Installing the gem

gem install restapi_doc

Set Up

Run the following rake command to setup your environment.

rake restapi_doc:generate

This will create a ‘restapi_doc’ directory in your Rails config directory. In this directory you will now have a “restapi_doc.yml’ file with some simple configuration options for your API document.

Documenting Controller class

Below is a sample of how to document a class.

# =begin apidoc
# Description of class
# =end

Documenting controllers methods

Below is a sample of how to document the controller to generate a document

# =begin apidoc
# method:: POST
# requires_authentication:: Yes
# response_format:: json
# response_format:: xml
# param:: Name - string - required - Users name
# param:: Email - string - required - Users email address
# param:: Password - string - required - Users password.
#
# http_response:: 201 - Created - Returns user object
# http_response:: 401 - Not Authorized - Not authorized
# http_response:: 422 - Unprocessable Entity - Unable to process parameters
#
# request:: json
# {
#  "name":"Linda Clarkson",
#  "email":"athatcher@yahoo.com",
#  "password":"Hl108dLpSr"
# }
# ::request-end::
#
# output:: json
# {
#    "_id":"4f9778fe4736df029c000003",
#    "created_at":"2012-04-24T21:09:34-07:00",
#    "email":"athatcher@yahoo.com",
#    "name":"Linda Clarkson"
# }
# ::output-end::
#
#
# Creates a new user
# =end

Creating Api Document

rake restapi_doc:generate

You will now have a ‘apidoc’ directory located in your Rails ‘public’ directory