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