Add a max_per_page option for Grape. Closes #22 and #23

Signed-off-by: David Celis <me@davidcel.is>

Author: davidcelis

README.md

@@ -49,7 +49,7 @@ class MoviesController < ApplicationController
 end
 ```
 
-This will pull your collection from the `json` or `xml` option, paginate it for you using `params[:page]` and `params[:per_page]`, render Link headers, and call `ActionController::Base#render` with whatever you passed to `paginate`. This should work well with [ActiveModel::Serializers](https://github.com/rails-api/active_model-serializers). However, if you need more control over what is done with your paginated collection, you can pass the collection directly to `paginate` instead of in a way that mimics `render`:
+This will pull your collection from the `json` or `xml` option, paginate it for you using `params[:page]` and `params[:per_page]`, render Link headers, and call `ActionController::Base#render` with whatever you passed to `paginate`. This should work well with [ActiveModel::Serializers](https://github.com/rails-api/active_model-serializers). However, if you need more control over what is done with your paginated collection, you can pass the collection directly to `paginate` to receive a paginated collection and have your headers set. Then, you can pass that paginated collection to a serializer or do whatever you want with it:
 
 ```ruby
 class MoviesController < ApplicationController
@@ -69,13 +69,11 @@ class MoviesController < ApplicationController
 end
 ```
 
-This will avoid implicitly calling `render` at the end. Instead, `paginate` will simply set up the headers and return your collection so you can do whatever you want with it.
-
-Note that the collection sent to `paginate` _must_ respond to your paginator's methods. For Kaminari, `Kaminari.paginate_array` will be called for you behind-the-scenes. For WillPaginate, you're out of luck unless you call `require 'will_paginate/array'` somewhere. Because this pollutes `Array`, it won't be done for you automatically.
+Note that the collection sent to `paginate` _must_ respond to your paginator's methods. This is typically fine unless you're dealing with a stock Array. For Kaminari, `Kaminari.paginate_array` will be called for you behind-the-scenes. For WillPaginate, you're out of luck unless you call `require 'will_paginate/array'` somewhere. Because this pollutes `Array`, it won't be done for you automatically.
 
 ## Grape
 
-With Grape, `paginate` is used to declare that your endpoint takes a `:page` and `:per_page` param. Inside your API endpoint, it simply takes your collection:
+With Grape, `paginate` is used to declare that your endpoint takes a `:page` and `:per_page` param. You can also directly specify a `:max_per_page` that users aren't allowed to go over. Then, inside your API endpoint, it simply takes your collection:
 
 ```ruby
 class MoviesAPI < Grape::API
@@ -93,7 +91,8 @@ class MoviesAPI < Grape::API
     desc "Return one movie's cast, paginated"
     # Override how many Actors get returned. If unspecified,
     # params[:per_page] (which defaults to 25) will be used.
-    paginate per_page: 10
+    # There is no default for `max_per_page`.
+    paginate per_page: 10, max_per_page: 200
     get :cast do
       paginate Movie.find(params[:id]).actors
     end

lib/grape/pagination.rb

@@ -3,9 +3,10 @@ module Pagination
     def self.included(base)
       Grape::Endpoint.class_eval do
         def paginate(collection)
+          per_page = params[:per_page] || route_setting(:per_page)
           options = {
             :page     => params[:page],
-            :per_page => (params[:per_page] || route_setting(:per_page))
+            :per_page => [per_page, route_setting(:max_per_page)].compact.min
           }
           collection = ApiPagination.paginate(collection, options)
 
@@ -30,6 +31,7 @@ def paginate(collection)
       base.class_eval do
         def self.paginate(options = {})
           route_setting :per_page, (options[:per_page] || 25)
+          route_setting :max_per_page, options[:max_per_page]
           params do
             optional :page,     :type => Integer, :default => 1,
                                 :desc => 'Page of results to fetch.'

spec/grape_spec.rb

@@ -55,6 +55,16 @@
 
         it_behaves_like 'an endpoint with a middle page'
       end
+
+      context 'with a max_per_page setting' do
+        before { get '/numbers', :count => 100, :per_page => 30 }
+
+        it 'should not go above the max_per_page_limit' do
+          body = '[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25]'
+
+          expect(last_response.body).to eq(body)
+        end
+      end
     end
   end
 end

spec/support/numbers_api.rb

@@ -5,7 +5,7 @@ class NumbersAPI < Grape::API
   format :json
 
   desc 'Return some paginated set of numbers'
-  paginate :per_page => 10
+  paginate :per_page => 10, :max_per_page => 25 
   params do
     requires :count, :type => Integer
     optional :with_headers, :default => false, :type => Boolean