An example of how rapi_doc is setup

books_controller.rb

class BooksController < ApplicationController
  # GET /books
  # GET /books.json
#=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":"the United States of America has collapsed, to be replaced by Panem, a country divided into the Capitol and 12 districts.",
#     "id":1,
#     "price":19,
#     "title":"The Hunger Games",
#     "updated_at":"2011-12-05T09:46:11Z" },
#   { "created_at":"2011-12-05T09:46:43Z",
#     "description":"As with the last several books in the series, V Is for Vengeance was a long time in the making.",
#     "id":2,
#     "price":11,
#     "title":"V is for Vengeance",
#     "updated_at":"2011-12-05T09:46:43Z" }
# ]
# ::output-end::
# output:: xml
# <books type="array">
#   <book>
#     <id type="integer">1</id>
#     <title>The Hunger Games</title>
#     <description>the United States of America has collapsed, to be replaced by Panem, a country divided into the Capitol and 12 districts.</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>
#   <book>
#     <id type="integer">2</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">11</price>
#     <created-at type="datetime">2011-12-05T09:46:43Z</created-at>
#     <updated-at type="datetime">2011-12-05T09:46:43Z</updated-at>
#   </book>
# </books>
#::output-end::
# Get a list of all books in the system with pagination.  Defaults to 10 per page
#=end
  def index
    @books = Book.all

    respond_to do |format|
      format.html # index.html.erb
      format.json { render json: @books }
      format.xml  { render xml:  @books }
    end
  end

  # GET /books/1
  # GET /books/1.json
#=begin apidoc
#url:: /books/{id}
#method:: GET
#access:: FREE
#return:: [JSON|XML] - attributes of a book object
#param:: id:int - the book ID
# output:: json
# { "created_at":"2011-12-05T09:46:11Z",
#   "description":"the United States of America has collapsed, to be replaced by Panem, a country divided into the Capitol and 12 districts.",
#   "id":1,
#   "price":19,
#   "title":"The Hunger Games",
#   "updated_at":"2011-12-05T09:46:11Z" 
# }
# ::output-end::
# output:: xml
# <book>
#   <id type="integer">1</id>
#   <title>The Hunger Games</title>
#   <description>the United States of America has collapsed, to be replaced by Panem, a country divided into the Capitol and 12 districts.</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>
#::output-end::
# Get a list of all books in the system with pagination.  Defaults to 10 per page
#=end
  def show
    @book = Book.find(params[:id])

    respond_to do |format|
      format.html # show.html.erb
      format.json { render json: @book }
      format.xml { render xml: @book }
    end
  end

end

config.yml

books:
 location: "/books"
 controller_name: "books_controller.rb"