grape-security 0.8.0

data/spec/grape/validations/presence_spec.rb

@@ -0,0 +1,142 @@
+require 'spec_helper'
+
+describe Grape::Validations::PresenceValidator do
+
+  module ValidationsSpec
+    module PresenceValidatorSpec
+      class API < Grape::API
+        default_format :json
+
+        resource :bacons do
+          get do
+            "All the bacon"
+          end
+        end
+
+        params do
+          requires :id, regexp: /^[0-9]+$/
+        end
+        post do
+          { ret: params[:id] }
+        end
+
+        params do
+          requires :name, :company
+        end
+        get do
+          "Hello"
+        end
+
+        params do
+          requires :user, type: Hash do
+            requires :first_name
+            requires :last_name
+          end
+        end
+        get '/nested' do
+          "Nested"
+        end
+
+        params do
+          requires :admin, type: Hash do
+            requires :admin_name
+            requires :super, type: Hash do
+              requires :user, type: Hash do
+                requires :first_name
+                requires :last_name
+              end
+            end
+          end
+        end
+        get '/nested_triple' do
+          "Nested triple"
+        end
+      end
+    end
+  end
+
+  def app
+    ValidationsSpec::PresenceValidatorSpec::API
+  end
+
+  it 'does not validate for any params' do
+    get "/bacons"
+    expect(last_response.status).to eq(200)
+    expect(last_response.body).to eq("All the bacon".to_json)
+  end
+
+  it 'validates id' do
+    post '/'
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('{"error":"id is missing"}')
+
+    io = StringIO.new('{"id" : "a56b"}')
+    post '/', {}, 'rack.input' => io, 'CONTENT_TYPE' => 'application/json', 'CONTENT_LENGTH' => io.length
+    expect(last_response.body).to eq('{"error":"id is invalid"}')
+    expect(last_response.status).to eq(400)
+
+    io = StringIO.new('{"id" : 56}')
+    post '/', {}, 'rack.input' => io, 'CONTENT_TYPE' => 'application/json', 'CONTENT_LENGTH' => io.length
+    expect(last_response.body).to eq('{"ret":56}')
+    expect(last_response.status).to eq(201)
+  end
+
+  it 'validates name, company' do
+    get '/'
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('{"error":"name is missing"}')
+
+    get '/', name: "Bob"
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('{"error":"company is missing"}')
+
+    get '/', name: "Bob", company: "TestCorp"
+    expect(last_response.status).to eq(200)
+    expect(last_response.body).to eq("Hello".to_json)
+  end
+
+  it 'validates nested parameters' do
+    get '/nested'
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('{"error":"user is missing, user[first_name] is missing, user[last_name] is missing"}')
+
+    get '/nested', user: { first_name: "Billy" }
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('{"error":"user[last_name] is missing"}')
+
+    get '/nested', user: { first_name: "Billy", last_name: "Bob" }
+    expect(last_response.status).to eq(200)
+    expect(last_response.body).to eq("Nested".to_json)
+  end
+
+  it 'validates triple nested parameters' do
+    get '/nested_triple'
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to include '{"error":"admin is missing'
+
+    get '/nested_triple', user: { first_name: "Billy" }
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to include '{"error":"admin is missing'
+
+    get '/nested_triple', admin: { super: { first_name: "Billy" } }
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('{"error":"admin[admin_name] is missing, admin[super][user] is missing, admin[super][user][first_name] is missing, admin[super][user][last_name] is missing"}')
+
+    get '/nested_triple', super: { user: { first_name: "Billy", last_name: "Bob" } }
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to include '{"error":"admin is missing'
+
+    get '/nested_triple', admin: { super: { user: { first_name: "Billy" } } }
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('{"error":"admin[admin_name] is missing, admin[super][user][last_name] is missing"}')
+
+    get '/nested_triple', admin: { admin_name: 'admin', super: { user: { first_name: "Billy" } } }
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('{"error":"admin[super][user][last_name] is missing"}')
+
+    get '/nested_triple', admin: { admin_name: 'admin', super: { user: { first_name: "Billy", last_name: "Bob" } } }
+    expect(last_response.status).to eq(200)
+    expect(last_response.body).to eq("Nested triple".to_json)
+  end
+
+end

data/spec/grape/validations/regexp_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+
+describe Grape::Validations::RegexpValidator do
+  module ValidationsSpec
+    module RegexpValidatorSpec
+      class API < Grape::API
+        default_format :json
+
+        params do
+          requires :name, regexp: /^[a-z]+$/
+        end
+        get do
+
+        end
+      end
+    end
+  end
+
+  def app
+    ValidationsSpec::RegexpValidatorSpec::API
+  end
+
+  context 'invalid input' do
+    it 'refuses inapppopriate' do
+      get '/', name: "invalid name"
+      expect(last_response.status).to eq(400)
+    end
+
+    it 'refuses nil' do
+      get '/', name: nil
+      expect(last_response.status).to eq(400)
+    end
+  end
+
+  it 'accepts valid input' do
+    get '/', name: "bob"
+    expect(last_response.status).to eq(200)
+  end
+
+end

data/spec/grape/validations/values_spec.rb

@@ -0,0 +1,152 @@
+require 'spec_helper'
+
+describe Grape::Validations::ValuesValidator do
+
+  class ValuesModel
+    DEFAULT_VALUES = ['valid-type1', 'valid-type2', 'valid-type3']
+    class << self
+      def values
+        @values ||= []
+        [DEFAULT_VALUES + @values].flatten.uniq
+      end
+
+      def add_value(value)
+        @values ||= []
+        @values << value
+      end
+    end
+  end
+
+  module ValidationsSpec
+    module ValuesValidatorSpec
+      class API < Grape::API
+        default_format :json
+
+        params do
+          requires :type, values: ValuesModel.values
+        end
+        get '/' do
+          { type: params[:type] }
+        end
+
+        params do
+          optional :type, values: ValuesModel.values, default: 'valid-type2'
+        end
+        get '/default/valid' do
+          { type: params[:type] }
+        end
+
+        params do
+          optional :type, values: -> { ValuesModel.values }, default: 'valid-type2'
+        end
+        get '/lambda' do
+          { type: params[:type] }
+        end
+
+        params do
+          requires :type, type: Integer, desc: "An integer", values: [10, 11], default: 10
+        end
+        get '/values/coercion' do
+          { type: params[:type] }
+        end
+
+        params do
+          optional :optional do
+            requires :type, values: ["a", "b"]
+          end
+        end
+        get '/optional_with_required_values'
+      end
+    end
+  end
+
+  def app
+    ValidationsSpec::ValuesValidatorSpec::API
+  end
+
+  it 'allows a valid value for a parameter' do
+    get("/", type: 'valid-type1')
+    expect(last_response.status).to eq 200
+    expect(last_response.body).to eq({ type: "valid-type1" }.to_json)
+  end
+
+  it 'does not allow an invalid value for a parameter' do
+    get("/", type: 'invalid-type')
+    expect(last_response.status).to eq 400
+    expect(last_response.body).to eq({ error: "type does not have a valid value" }.to_json)
+  end
+
+  context 'nil value for a parameter' do
+    it 'does not allow for root params scope' do
+      get("/", type: nil)
+      expect(last_response.status).to eq 400
+      expect(last_response.body).to eq({ error: "type does not have a valid value" }.to_json)
+    end
+
+    it 'allows for a required param in child scope' do
+      get('/optional_with_required_values')
+      expect(last_response.status).to eq 200
+    end
+  end
+
+  it 'allows a valid default value' do
+    get("/default/valid")
+    expect(last_response.status).to eq 200
+    expect(last_response.body).to eq({ type: "valid-type2" }.to_json)
+  end
+
+  it 'allows a proc for values' do
+    get('/lambda', type: 'valid-type1')
+    expect(last_response.status).to eq 200
+    expect(last_response.body).to eq({ type: "valid-type1" }.to_json)
+  end
+
+  it 'does not validate updated values without proc' do
+    ValuesModel.add_value('valid-type4')
+
+    get('/', type: 'valid-type4')
+    expect(last_response.status).to eq 400
+    expect(last_response.body).to eq({ error: "type does not have a valid value" }.to_json)
+  end
+
+  it 'validates against values in a proc' do
+    ValuesModel.add_value('valid-type4')
+
+    get('/lambda', type: 'valid-type4')
+    expect(last_response.status).to eq 200
+    expect(last_response.body).to eq({ type: "valid-type4" }.to_json)
+  end
+
+  it 'does not allow an invalid value for a parameter using lambda' do
+    get("/lambda", type: 'invalid-type')
+    expect(last_response.status).to eq 400
+    expect(last_response.body).to eq({ error: "type does not have a valid value" }.to_json)
+  end
+
+  it 'raises IncompatibleOptionValues on an invalid default value' do
+    subject = Class.new(Grape::API)
+    expect {
+      subject.params { optional :type, values: ['valid-type1', 'valid-type2', 'valid-type3'], default: 'invalid-type' }
+    }.to raise_error Grape::Exceptions::IncompatibleOptionValues
+  end
+
+  it 'raises IncompatibleOptionValues when type is incompatible with values array' do
+    subject = Class.new(Grape::API)
+    expect {
+      subject.params { optional :type, values: ['valid-type1', 'valid-type2', 'valid-type3'], type: Symbol }
+    }.to raise_error Grape::Exceptions::IncompatibleOptionValues
+  end
+
+  it 'allows values to be a kind of the coerced type not just an instance of it' do
+    get("/values/coercion", type: 10)
+    expect(last_response.status).to eq 200
+    expect(last_response.body).to eq({ type: 10 }.to_json)
+  end
+
+  it 'raises IncompatibleOptionValues when values contains a value that is not a kind of the type' do
+    subject = Class.new(Grape::API)
+    expect {
+      subject.params { requires :type, values: [10.5, 11], type: Integer }
+    }.to raise_error Grape::Exceptions::IncompatibleOptionValues
+  end
+end

data/spec/grape/validations/zh-CN.yml

@@ -0,0 +1,10 @@
+zh-CN:
+  grape:
+    errors:
+      format: ! '%{attribute}%{message}'
+      attributes:
+        age: 年龄
+      messages:
+        coerce: '格式不正确'
+        presence: '请填写'
+        regexp: '格式不正确'

data/spec/grape/validations_spec.rb

@@ -0,0 +1,994 @@
+require 'spec_helper'
+
+describe Grape::Validations do
+
+  subject { Class.new(Grape::API) }
+
+  def app
+    subject
+  end
+
+  describe 'params' do
+    context 'optional' do
+      it 'validates when params is present' do
+        subject.params do
+          optional :a_number, regexp: /^[0-9]+$/
+        end
+        subject.get '/optional' do
+          'optional works!'
+        end
+
+        get '/optional', a_number: 'string'
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('a_number is invalid')
+
+        get '/optional', a_number: 45
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('optional works!')
+      end
+
+      it "doesn't validate when param not present" do
+        subject.params do
+          optional :a_number, regexp: /^[0-9]+$/
+        end
+        subject.get '/optional' do
+          'optional works!'
+        end
+
+        get '/optional'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('optional works!')
+      end
+
+      it 'adds to declared parameters' do
+        subject.params do
+          optional :some_param
+        end
+        expect(subject.settings[:declared_params]).to eq([:some_param])
+      end
+    end
+
+    context 'required' do
+      before do
+        subject.params do
+          requires :key
+        end
+        subject.get '/required' do
+          'required works'
+        end
+      end
+
+      it 'errors when param not present' do
+        get '/required'
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('key is missing')
+      end
+
+      it "doesn't throw a missing param when param is present" do
+        get '/required', key: 'cool'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('required works')
+      end
+
+      it 'adds to declared parameters' do
+        subject.params do
+          requires :some_param
+        end
+        expect(subject.settings[:declared_params]).to eq([:some_param])
+      end
+    end
+
+    context 'requires :all using Grape::Entity documentation' do
+      def define_requires_all
+        documentation = {
+          required_field: { type: String },
+          optional_field: { type: String }
+        }
+        subject.params do
+          requires :all, except: :optional_field, using: documentation
+        end
+      end
+      before do
+        define_requires_all
+        subject.get '/required' do
+          'required works'
+        end
+      end
+
+      it 'adds entity documentation to declared params' do
+        define_requires_all
+        expect(subject.settings[:declared_params]).to eq([:required_field, :optional_field])
+      end
+
+      it 'errors when required_field is not present' do
+        get '/required'
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('required_field is missing')
+      end
+
+      it 'works when required_field is present' do
+        get '/required', required_field: 'woof'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('required works')
+      end
+    end
+
+    context 'requires :none using Grape::Entity documentation' do
+      def define_requires_none
+        documentation = {
+          required_field: { type: String },
+          optional_field: { type: String }
+        }
+        subject.params do
+          requires :none, except: :required_field, using: documentation
+        end
+      end
+      before do
+        define_requires_none
+        subject.get '/required' do
+          'required works'
+        end
+      end
+
+      it 'adds entity documentation to declared params' do
+        define_requires_none
+        expect(subject.settings[:declared_params]).to eq([:required_field, :optional_field])
+      end
+
+      it 'errors when required_field is not present' do
+        get '/required'
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('required_field is missing')
+      end
+
+      it 'works when required_field is present' do
+        get '/required', required_field: 'woof'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('required works')
+      end
+    end
+
+    context 'requires :all or :none but except a non-existent field using Grape::Entity documentation' do
+      context 'requires :all' do
+        def define_requires_all
+          documentation = {
+            required_field: { type: String },
+            optional_field: { type: String }
+          }
+          subject.params do
+            requires :all, except: :non_existent_field, using: documentation
+          end
+        end
+
+        it 'adds only the entity documentation to declared params, nothing more' do
+          define_requires_all
+          expect(subject.settings[:declared_params]).to eq([:required_field, :optional_field])
+        end
+      end
+
+      context 'requires :none' do
+        def define_requires_none
+          documentation = {
+            required_field: { type: String },
+            optional_field: { type: String }
+          }
+          subject.params do
+            requires :none, except: :non_existent_field, using: documentation
+          end
+        end
+
+        it 'adds only the entity documentation to declared params, nothing more' do
+          expect { define_requires_none }.to raise_error(ArgumentError)
+        end
+      end
+    end
+
+    context 'required with an Array block' do
+      before do
+        subject.params do
+          requires :items, type: Array do
+            requires :key
+          end
+        end
+        subject.get '/required' do
+          'required works'
+        end
+      end
+
+      it 'errors when param not present' do
+        get '/required'
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is missing')
+      end
+
+      it "errors when param is not an Array" do
+        get '/required', items: "hello"
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is invalid, items[key] is missing')
+
+        get '/required', items: { key: 'foo' }
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is invalid')
+      end
+
+      it "doesn't throw a missing param when param is present" do
+        get '/required', items: [{ key: 'hello' }, { key: 'world' }]
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('required works')
+      end
+
+      it "doesn't allow any key in the options hash other than type" do
+        expect {
+          subject.params do
+            requires(:items, desc: 'Foo') do
+              requires :key
+            end
+          end
+        }.to raise_error ArgumentError
+      end
+
+      it 'adds to declared parameters' do
+        subject.params do
+          requires :items do
+            requires :key
+          end
+        end
+        expect(subject.settings[:declared_params]).to eq([items: [:key]])
+      end
+    end
+
+    context 'required with a Hash block' do
+      before do
+        subject.params do
+          requires :items, type: Hash do
+            requires :key
+          end
+        end
+        subject.get '/required' do
+          'required works'
+        end
+      end
+
+      it 'errors when param not present' do
+        get '/required'
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is missing, items[key] is missing')
+      end
+
+      it "errors when param is not a Hash" do
+        get '/required', items: "hello"
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is invalid, items[key] is missing')
+
+        get '/required', items: [{ key: 'foo' }]
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is invalid')
+      end
+
+      it "doesn't throw a missing param when param is present" do
+        get '/required', items: { key: 'hello' }
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('required works')
+      end
+
+      it "doesn't allow any key in the options hash other than type" do
+        expect {
+          subject.params do
+            requires(:items, desc: 'Foo') do
+              requires :key
+            end
+          end
+        }.to raise_error ArgumentError
+      end
+
+      it 'adds to declared parameters' do
+        subject.params do
+          requires :items do
+            requires :key
+          end
+        end
+        expect(subject.settings[:declared_params]).to eq([items: [:key]])
+      end
+    end
+
+    context 'group' do
+      before do
+        subject.params do
+          group :items do
+            requires :key
+          end
+        end
+        subject.get '/required' do
+          'required works'
+        end
+      end
+
+      it 'errors when param not present' do
+        get '/required'
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is missing')
+      end
+
+      it "doesn't throw a missing param when param is present" do
+        get '/required', items: [key: 'hello', key: 'world']
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('required works')
+      end
+
+      it 'adds to declared parameters' do
+        subject.params do
+          group :items do
+            requires :key
+          end
+        end
+        expect(subject.settings[:declared_params]).to eq([items: [:key]])
+      end
+    end
+
+    context 'validation within arrays' do
+      before do
+        subject.params do
+          group :children do
+            requires :name
+            group :parents do
+              requires :name
+            end
+          end
+        end
+        subject.get '/within_array' do
+          'within array works'
+        end
+      end
+
+      it 'can handle new scopes within child elements' do
+        get '/within_array', children: [
+          { name: 'John', parents: [{ name: 'Jane' }, { name: 'Bob' }] },
+          { name: 'Joe', parents: [{ name: 'Josie' }] }
+        ]
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('within array works')
+      end
+
+      it 'errors when a parameter is not present' do
+        get '/within_array', children: [
+          { name: 'Jim', parents: [{}] },
+          { name: 'Job', parents: [{ name: 'Joy' }] }
+        ]
+        # NOTE: with body parameters in json or XML or similar this
+        # should actually fail with: children[parents][name] is missing.
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('children[parents] is missing')
+      end
+
+      it 'safely handles empty arrays and blank parameters' do
+        # NOTE: with body parameters in json or XML or similar this
+        # should actually return 200, since an empty array is valid.
+        get '/within_array', children: []
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('children is missing')
+        get '/within_array', children: [name: 'Jay']
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('children[parents] is missing')
+      end
+
+      it "errors when param is not an Array" do
+        # NOTE: would be nicer if these just returned 'children is invalid'
+        get '/within_array', children: "hello"
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('children is invalid, children[name] is missing, children[parents] is missing, children[parents] is invalid, children[parents][name] is missing')
+
+        get '/within_array', children: { name: 'foo' }
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('children is invalid, children[parents] is missing')
+
+        get '/within_array', children: [name: 'Jay', parents: { name: 'Fred' }]
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('children[parents] is invalid')
+      end
+    end
+
+    context 'with block param' do
+      before do
+        subject.params do
+          requires :planets do
+            requires :name
+          end
+        end
+        subject.get '/req' do
+          'within array works'
+        end
+        subject.put '/req' do
+          ''
+        end
+
+        subject.params do
+          group :stars do
+            requires :name
+          end
+        end
+        subject.get '/grp' do
+          'within array works'
+        end
+        subject.put '/grp' do
+          ''
+        end
+
+        subject.params do
+          requires :name
+          optional :moons do
+            requires :name
+          end
+        end
+        subject.get '/opt' do
+          'within array works'
+        end
+        subject.put '/opt' do
+          ''
+        end
+      end
+
+      it 'requires defaults to Array type' do
+        get '/req', planets: "Jupiter, Saturn"
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('planets is invalid, planets[name] is missing')
+
+        get '/req', planets: { name: 'Jupiter' }
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('planets is invalid')
+
+        get '/req', planets: [{ name: 'Venus' }, { name: 'Mars' }]
+        expect(last_response.status).to eq(200)
+
+        put_with_json '/req', planets: []
+        expect(last_response.status).to eq(200)
+      end
+
+      it 'optional defaults to Array type' do
+        get '/opt', name: "Jupiter", moons: "Europa, Ganymede"
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('moons is invalid, moons[name] is missing')
+
+        get '/opt', name: "Jupiter", moons: { name: 'Ganymede' }
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('moons is invalid')
+
+        get '/opt', name: "Jupiter", moons: [{ name: 'Io' }, { name: 'Callisto' }]
+        expect(last_response.status).to eq(200)
+
+        put_with_json '/opt', name: "Venus"
+        expect(last_response.status).to eq(200)
+
+        put_with_json '/opt', name: "Mercury", moons: []
+        expect(last_response.status).to eq(200)
+      end
+
+      it 'group defaults to Array type' do
+        get '/grp', stars: "Sun"
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('stars is invalid, stars[name] is missing')
+
+        get '/grp', stars: { name: 'Sun' }
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('stars is invalid')
+
+        get '/grp', stars: [{ name: 'Sun' }]
+        expect(last_response.status).to eq(200)
+
+        put_with_json '/grp', stars: []
+        expect(last_response.status).to eq(200)
+      end
+    end
+
+    context 'validation within arrays with JSON' do
+      before do
+        subject.params do
+          group :children do
+            requires :name
+            group :parents do
+              requires :name
+            end
+          end
+        end
+        subject.put '/within_array' do
+          'within array works'
+        end
+      end
+
+      it 'can handle new scopes within child elements' do
+        put_with_json '/within_array', children: [
+          { name: 'John', parents: [{ name: 'Jane' }, { name: 'Bob' }] },
+          { name: 'Joe', parents: [{ name: 'Josie' }] }
+        ]
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('within array works')
+      end
+
+      it 'errors when a parameter is not present' do
+        put_with_json '/within_array', children: [
+          { name: 'Jim', parents: [{}] },
+          { name: 'Job', parents: [{ name: 'Joy' }] }
+        ]
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('children[parents][name] is missing')
+      end
+
+      it 'safely handles empty arrays and blank parameters' do
+        put_with_json '/within_array', children: []
+        expect(last_response.status).to eq(200)
+        put_with_json '/within_array', children: [name: 'Jay']
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('children[parents] is missing')
+      end
+    end
+
+    context 'optional with an Array block' do
+      before do
+        subject.params do
+          optional :items, type: Array do
+            requires :key
+          end
+        end
+        subject.get '/optional_group' do
+          'optional group works'
+        end
+      end
+
+      it "doesn't throw a missing param when the group isn't present" do
+        get '/optional_group'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('optional group works')
+      end
+
+      it "doesn't throw a missing param when both group and param are given" do
+        get '/optional_group', items: [{ key: 'foo' }]
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('optional group works')
+      end
+
+      it "errors when group is present, but required param is not" do
+        get '/optional_group', items: [{ not_key: 'foo' }]
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items[key] is missing')
+      end
+
+      it "errors when param is present but isn't an Array" do
+        get '/optional_group', items: "hello"
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is invalid, items[key] is missing')
+
+        get '/optional_group', items: { key: 'foo' }
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items is invalid')
+      end
+
+      it 'adds to declared parameters' do
+        subject.params do
+          optional :items do
+            requires :key
+          end
+        end
+        expect(subject.settings[:declared_params]).to eq([items: [:key]])
+      end
+    end
+
+    context 'nested optional Array blocks' do
+      before do
+        subject.params do
+          optional :items, type: Array do
+            requires :key
+            optional(:optional_subitems, type: Array) { requires :value }
+            requires(:required_subitems, type: Array) { requires :value }
+          end
+        end
+        subject.get('/nested_optional_group') { 'nested optional group works' }
+      end
+
+      it 'does no internal validations if the outer group is blank' do
+        get '/nested_optional_group'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('nested optional group works')
+      end
+
+      it 'does internal validations if the outer group is present' do
+        get '/nested_optional_group', items: [{ key: 'foo' }]
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items[required_subitems] is missing')
+
+        get '/nested_optional_group', items: [{ key: 'foo', required_subitems: [{ value: 'bar' }] }]
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('nested optional group works')
+      end
+
+      it 'handles deep nesting' do
+        get '/nested_optional_group', items: [{ key: 'foo', required_subitems: [{ value: 'bar' }], optional_subitems: [{ not_value: 'baz' }] }]
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items[optional_subitems][value] is missing')
+
+        get '/nested_optional_group', items: [{ key: 'foo', required_subitems: [{ value: 'bar' }], optional_subitems: [{ value: 'baz' }] }]
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('nested optional group works')
+      end
+
+      it 'handles validation within arrays' do
+        get '/nested_optional_group', items: [{ key: 'foo' }]
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items[required_subitems] is missing')
+
+        get '/nested_optional_group', items: [{ key: 'foo', required_subitems: [{ value: 'bar' }] }]
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('nested optional group works')
+
+        get '/nested_optional_group', items: [{ key: 'foo', required_subitems: [{ value: 'bar' }], optional_subitems: [{ not_value: 'baz' }] }]
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to eq('items[optional_subitems][value] is missing')
+      end
+
+      it 'adds to declared parameters' do
+        subject.params do
+          optional :items do
+            requires :key
+            optional(:optional_subitems) { requires :value }
+            requires(:required_subitems) { requires :value }
+          end
+        end
+        expect(subject.settings[:declared_params]).to eq([items: [:key, { optional_subitems: [:value] }, { required_subitems: [:value] }]])
+      end
+    end
+
+    context 'multiple validation errors' do
+      before do
+        subject.params do
+          requires :yolo
+          requires :swag
+        end
+        subject.get '/two_required' do
+          'two required works'
+        end
+      end
+
+      it 'throws the validation errors' do
+        get '/two_required'
+        expect(last_response.status).to eq(400)
+        expect(last_response.body).to match(/yolo is missing/)
+        expect(last_response.body).to match(/swag is missing/)
+      end
+    end
+
+    context 'custom validation' do
+      module CustomValidations
+        class Customvalidator < Grape::Validations::Validator
+          def validate_param!(attr_name, params)
+            unless params[attr_name] == 'im custom'
+              raise Grape::Exceptions::Validation, param: @scope.full_name(attr_name), message: "is not custom!"
+            end
+          end
+        end
+      end
+
+      context 'when using optional with a custom validator' do
+        before do
+          subject.params do
+            optional :custom, customvalidator: true
+          end
+          subject.get '/optional_custom' do
+            'optional with custom works!'
+          end
+        end
+
+        it 'validates when param is present' do
+          get '/optional_custom', custom: 'im custom'
+          expect(last_response.status).to eq(200)
+          expect(last_response.body).to eq('optional with custom works!')
+
+          get '/optional_custom', custom: 'im wrong'
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to eq('custom is not custom!')
+        end
+
+        it "skips validation when parameter isn't present" do
+          get '/optional_custom'
+          expect(last_response.status).to eq(200)
+          expect(last_response.body).to eq('optional with custom works!')
+        end
+
+        it 'validates with custom validator when param present and incorrect type' do
+          subject.params do
+            optional :custom, type: String, customvalidator: true
+          end
+
+          get '/optional_custom', custom: 123
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to eq('custom is not custom!')
+        end
+      end
+
+      context 'when using requires with a custom validator' do
+        before do
+          subject.params do
+            requires :custom, customvalidator: true
+          end
+          subject.get '/required_custom' do
+            'required with custom works!'
+          end
+        end
+
+        it 'validates when param is present' do
+          get '/required_custom', custom: 'im wrong, validate me'
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to eq('custom is not custom!')
+
+          get '/required_custom', custom: 'im custom'
+          expect(last_response.status).to eq(200)
+          expect(last_response.body).to eq('required with custom works!')
+        end
+
+        it 'validates when param is not present' do
+          get '/required_custom'
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to eq('custom is missing, custom is not custom!')
+        end
+
+        context 'nested namespaces' do
+          before do
+            subject.params do
+              requires :custom, customvalidator: true
+            end
+            subject.namespace 'nested' do
+              get 'one' do
+                'validation failed'
+              end
+              namespace 'nested' do
+                get 'two' do
+                  'validation failed'
+                end
+              end
+            end
+            subject.namespace 'peer' do
+              get 'one' do
+                'no validation required'
+              end
+              namespace 'nested' do
+                get 'two' do
+                  'no validation required'
+                end
+              end
+            end
+
+            subject.namespace 'unrelated' do
+              params do
+                requires :name
+              end
+              get 'one' do
+                'validation required'
+              end
+
+              namespace 'double' do
+                get 'two' do
+                  'no validation required'
+                end
+              end
+            end
+          end
+
+          specify 'the parent namespace uses the validator' do
+            get '/nested/one', custom: 'im wrong, validate me'
+            expect(last_response.status).to eq(400)
+            expect(last_response.body).to eq('custom is not custom!')
+          end
+
+          specify 'the nested namesapce inherits the custom validator' do
+            get '/nested/nested/two', custom: 'im wrong, validate me'
+            expect(last_response.status).to eq(400)
+            expect(last_response.body).to eq('custom is not custom!')
+          end
+
+          specify 'peer namesapces does not have the validator' do
+            get '/peer/one', custom: 'im not validated'
+            expect(last_response.status).to eq(200)
+            expect(last_response.body).to eq('no validation required')
+          end
+
+          specify 'namespaces nested in peers should also not have the validator' do
+            get '/peer/nested/two', custom: 'im not validated'
+            expect(last_response.status).to eq(200)
+            expect(last_response.body).to eq('no validation required')
+          end
+
+          specify 'when nested, specifying a route should clear out the validations for deeper nested params' do
+            get '/unrelated/one'
+            expect(last_response.status).to eq(400)
+            get '/unrelated/double/two'
+            expect(last_response.status).to eq(200)
+          end
+        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
+          expect(subject.settings[:declared_params]).to eq [:page, :per_page]
+        end
+
+        it 'by #use with multiple params' do
+          subject.params do
+            use :pagination, :period
+          end
+          expect(subject.settings[:declared_params]).to eq [:page, :per_page, :start_date, :end_date]
+        end
+
+      end
+
+      context 'with block' do
+        before do
+          subject.helpers do
+            params :order do |options|
+              optional :order, type: Symbol, values: [:asc, :desc], default: options[:default_order]
+              optional :order_by, type: Symbol, values: options[:order_by], default: options[:default_order_by]
+            end
+          end
+          subject.format :json
+          subject.params do
+            use :order, default_order: :asc, order_by: [:name, :created_at], default_order_by: :created_at
+          end
+          subject.get '/order' do
+            {
+              order: params[:order],
+              order_by: params[:order_by]
+            }
+          end
+        end
+        it 'returns defaults' do
+          get '/order'
+          expect(last_response.status).to eq(200)
+          expect(last_response.body).to eq({ order: :asc, order_by: :created_at }.to_json)
+        end
+        it 'overrides default value for order' do
+          get '/order?order=desc'
+          expect(last_response.status).to eq(200)
+          expect(last_response.body).to eq({ order: :desc, order_by: :created_at }.to_json)
+        end
+        it 'overrides default value for order_by' do
+          get '/order?order_by=name'
+          expect(last_response.status).to eq(200)
+          expect(last_response.body).to eq({ order: :asc, order_by: :name }.to_json)
+        end
+        it 'fails with invalid value' do
+          get '/order?order=invalid'
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to eq('{"error":"order does not have a valid value"}')
+        end
+      end
+    end
+
+    context 'documentation' do
+      it 'can be included with a hash' do
+        documentation = { example: 'Joe' }
+
+        subject.params do
+          requires 'first_name', documentation: documentation
+        end
+        subject.get '/' do
+        end
+
+        expect(subject.routes.first.route_params['first_name'][:documentation]).to eq(documentation)
+      end
+    end
+
+    context 'mutually exclusive' do
+      context 'optional params' do
+        it 'errors when two or more are present' do
+          subject.params do
+            optional :beer
+            optional :wine
+            optional :juice
+            mutually_exclusive :beer, :wine, :juice
+          end
+          subject.get '/mutually_exclusive' do
+            'mutually_exclusive works!'
+          end
+
+          get '/mutually_exclusive', beer: 'string', wine: 'anotherstring'
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to eq("[:beer, :wine] are mutually exclusive")
+        end
+      end
+
+      context 'more than one set of mutually exclusive params' do
+        it 'errors for all sets' do
+          subject.params do
+            optional :beer
+            optional :wine
+            mutually_exclusive :beer, :wine
+            optional :scotch
+            optional :aquavit
+            mutually_exclusive :scotch, :aquavit
+          end
+          subject.get '/mutually_exclusive' do
+            'mutually_exclusive works!'
+          end
+
+          get '/mutually_exclusive', beer: 'true', wine: 'true', scotch: 'true', aquavit: 'true'
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to match(/\[:beer, :wine\] are mutually exclusive/)
+          expect(last_response.body).to match(/\[:scotch, :aquavit\] are mutually exclusive/)
+        end
+      end
+    end
+
+    context 'exactly one of' do
+      context 'params' do
+        it 'errors when two or more are present' do
+          subject.params do
+            optional :beer
+            optional :wine
+            optional :juice
+            exactly_one_of :beer, :wine, :juice
+          end
+          subject.get '/exactly_one_of' do
+            'exactly_one_of works!'
+          end
+
+          get '/exactly_one_of', beer: 'string', wine: 'anotherstring'
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to eq("[:beer, :wine] are mutually exclusive")
+        end
+
+        it 'errors when none is selected' do
+          subject.params do
+            optional :beer
+            optional :wine
+            optional :juice
+            exactly_one_of :beer, :wine, :juice
+          end
+          subject.get '/exactly_one_of' do
+            'exactly_one_of works!'
+          end
+
+          get '/exactly_one_of'
+          expect(last_response.status).to eq(400)
+          expect(last_response.body).to eq("[:beer, :wine, :juice] - exactly one parameter must be provided")
+        end
+      end
+    end
+  end
+end