api.rb

ApiDocumentation.generate do
  
  common_params :pagination do
    param :page, 'The page to paginate to', :default => 1, :type => :integer
    param :per_page, 'Total number of entries to include on each page', :default => 10, :type => :integer
  end
  
  category :sessions do
    
    action('POST /signin.json') do
      param :email, :type => :string, :required => true
      param :password, :type => :string, :required => true
    end
    
    action('POST /signout.json')
    
  end
  
  category :users do
    
    common_params :user do
      param 'user[email]', 'An RFC2822 compliant email address', :required => true, :type => :string
      param 'user[password]', :required => true, :type => :string
      param 'user[password_confirmation]', :required => true, :type => :string      
    end
    
    action('GET /users.json') do
      common_params :pagination
    end
    
    action('GET /users/:user_id.json')
    
    action('POST /users.json') do
      common_params :user
    end
    
    action('PUT /users/:user_id.json') do
      common_params :user
    end
    
    action('DELETE /users/:user_id.json')
    
  end
  
  category :posts do
    
    action('GET /posts.json') do
      common_params :pagination
      param :types, 'Types of posts to include in the listing', :type => :array_of_strings, :default => %w(FooPost BarPost GoalPost), :options => %w(FooPost BarPost GoalPost NonDefaultPost)
      
      response :success, <<-EOS
        {
          "notices": [],
          "summary": { "pages": 1, "current_page": 1, "total_entries": 2 },
          "result": [
            {
              "id": 1,
              "type": "FooPost",
              "body": "My fantastical FooPost"
            }, {
              "id": 2,
              "type": "FooPost",
              "body": "My other (also) fantastical FooPost"
            }
          ]
        }
      EOS
      
    end
    
    action('GET /posts/:post_id.json')
    
    action('POST /posts.json') do
      param 'post[body]', :required => true, :type => :string
      param 'post[type]', :default => 'FooPost', :options => %w(FooPost BarPost GoalPost NonDefaultPost)
    end
    
    action('DELETE /posts/:post_id.json')
    
  end
  
end