Merge pull request #550 from dm1try/named_params

Add possibility to define reusable params.

Author: dblock

CHANGELOG.md

@@ -14,6 +14,7 @@ Next Release
 * [#540](https://github.com/intridea/grape/pull/540): Ruby 2.1.0 is now supported - [@salimane](https://github.com/salimane).
 * [#544](https://github.com/intridea/grape/pull/544): The `rescue_from` keyword now handles subclasses of exceptions by default - [@xevix](https://github.com/xevix).
 * [#545](https://github.com/intridea/grape/pull/545): Added `type` (Array or Hash) support to `requires`, `optional` and `group` - [@bwalex](https://github.com/bwalex).
+* [#550](https://github.com/intridea/grape/pull/550): Added possibility to define reusable params - [@dm1try](https://github.com/dm1try).
 * Your contribution here.
 
 #### Fixes

README.md

@@ -576,6 +576,58 @@ class API < Grape::API
 end
 ```
 
+You can define reusable `params` using `helpers`.
+
+```ruby
+class API < Grape::API
+ helpers do
+ params :pagination do
+ optional :page, type: Integer
+ optional :per_page, type: Integer
+ end
+ end
+
+ desc "Get collection"
+ params do
+ use :pagination # aliases: includes, use_scope
+ end
+ get do
+ Collection.page(params[:page]).per(params[:per_page])
+ end
+end
+```
+
+You can also define reusable `params` using shared helpers.
+
+```ruby
+module SharedParams
+ extend Grape::API::Helpers
+
+ params :period do
+ optional :start_date
+ optional :end_date
+ end
+
+ params :pagination do
+ optional :page, type: Integer
+ optional :per_page, type: Integer
+ end
+end
+
+class API < Grape::API
+ helpers SharedParams
+
+ desc "Get collection"
+ params do
+ use :period, :pagination
+ end
+ get do
+ Collection.from(params[:start_date]).to(params[:end_date])
+ .page(params[:page]).per(params[:per_page])
+ end
+end
+```
+
 ## Cookies
 
 You can set, get and delete your cookies very simply using `cookies` method.

lib/grape/api.rb

@@ -268,11 +268,16 @@ def helpers(new_mod = nil, &block)
  if block_given? || new_mod
  mod = settings.peek[:helpers] || Module.new
  if new_mod
+ inject_api_helpers_to_mod(new_mod) if new_mod.is_a?(Helpers)
  mod.class_eval do
  include new_mod
  end
  end
- mod.class_eval(&block) if block_given?
+ if block_given?
+ inject_api_helpers_to_mod(mod) do
+ mod.class_eval(&block)
+ end
+ end
  set(:helpers, mod)
  else
  mod = Module.new
@@ -509,6 +514,12 @@ def inherit_settings(other_stack)
  e.options[:app].inherit_settings(other_stack) if e.options[:app].respond_to?(:inherit_settings, true)
  end
  end
+
+ def inject_api_helpers_to_mod(mod, &block)
+ mod.extend(Helpers)
+ yield if block_given?
+ mod.api_changed(self)
+ end
  end
 
  def initialize
@@ -581,5 +592,28 @@ def add_head_not_allowed_methods_and_options_methods
  end
  end
  end
+
+ # This module extends user defined helpers
+ # to provide some API-specific functionality
+ module Helpers
+ attr_accessor :api
+ def params(name, &block)
+ @named_params ||= {}
+ @named_params.merge! name => block
+ end
+
+ def api_changed(new_api)
+ @api = new_api
+ process_named_params
+ end
+
+ protected
+
+ def process_named_params
+ if @named_params && @named_params.any?
+ api.imbue(:named_params, @named_params)
+ end
+ end
+ end
  end
 end

lib/grape/validations.rb

@@ -147,6 +147,18 @@ def params(params)
  params
  end
 
+ def use(*names)
+ named_params = @api.settings[:named_params] || {}
+ names.each do |name|
+ params_block = named_params.fetch(name) do
+ raise "Params :#{name} not found!"
+ end
+ instance_eval(&params_block)
+ end
+ end
+ alias_method :use_scope, :use
+ alias_method :includes, :use
+
  def full_name(name)
  return "#{@parent.full_name(@element)}[#{name}]" if @parent
  name.to_s

spec/grape/validations_spec.rb

@@ -698,5 +698,60 @@ def validate_param!(attr_name, params)
  end
  end
  end # end custom validation
+
+ context 'named' do
+ context 'can be defined' do
+ it 'in helpers' do
+ subject.helpers do
+ params :pagination do
+ end
+ end
+ end
+
+ it 'in helper module which kind of Grape::API::Helpers' do
+ module SharedParams
+ extend Grape::API::Helpers
+ params :pagination do
+ end
+ end
+ subject.helpers SharedParams
+ end
+ end
+
+ context 'can be included in usual params' do
+ before do
+ module SharedParams
+ extend Grape::API::Helpers
+ params :period do
+ optional :start_date
+ optional :end_date
+ end
+ end
+ subject.helpers SharedParams
+
+ subject.helpers do
+ params :pagination do
+ optional :page, type: Integer
+ optional :per_page, type: Integer
+ end
+ end
+ end
+
+ it 'by #use' do
+ subject.params do
+ use :pagination
+ end
+ subject.settings[:declared_params].should eq [:page, :per_page]
+ end
+
+ it 'by #use with multiple params' do
+ subject.params do
+ use :pagination, :period
+ end
+ subject.settings[:declared_params].should eq [:page, :per_page, :start_date, :end_date]
+ end
+
+ end
+ end
  end
 end