Added support for optional param documentation with using. Before…

… it did only work with `requires`.

CHANGELOG.md

@@ -8,6 +8,7 @@ Next Release
 * [#881](https://github.com/intridea/grape/issues/881): Fixed `Grape::Validations::ValuesValidator` support for `Range` type - [@ajvondrak](https://github.com/ajvondrak).
 * [#901](https://github.com/intridea/grape/pull/901): Fix: callbacks defined in a version block are only called for the routes defined in that block - [@kushkella](https://github.com/kushkella).
 * [#886](https://github.com/intridea/grape/pull/886): Group of parameters made to require an explicit type of Hash or Array - [@jrichter1](https://github.com/jrichter1).
+* [#912](https://github.com/intridea/grape/pull/912): Extended the `:using` feature for param documentation to `optional` fields - [@croeck](https://github.com/croeck).
 * Your contribution here.
 
 0.10.1 (12/28/2014)

lib/grape/dsl/parameters.rb

@@ -46,10 +46,14 @@ def optional(*attrs, &block)
           fail Grape::Exceptions::UnsupportedGroupTypeError.new unless [Array, Hash].include?(type)
         end
 
-        validate_attributes(attrs, opts, &block)
+        if opts[:using]
+          require_optional_fields(attrs.first, opts)
+        else
+          validate_attributes(attrs, opts, &block)
 
-        block_given? ? new_scope(orig_attrs, true, &block) :
-            push_declared_params(attrs)
+          block_given? ? new_scope(orig_attrs, true, &block) :
+              push_declared_params(attrs)
+        end
       end
 
       def mutually_exclusive(*attrs)

lib/grape/validations/params_scope.rb

@@ -64,6 +64,15 @@ def require_required_and_optional_fields(context, opts)
         end
       end
 
+      def require_optional_fields(context, opts)
+        optional_fields = opts[:using].keys
+        optional_fields -= Array(opts[:except]) unless context == :all
+        optional_fields.each do |field|
+          field_opts = opts[:using][field]
+          optional(field, field_opts) if field_opts
+        end
+      end
+
       def validate_attributes(attrs, opts, &block)
         validations = opts.clone
         validations[:type] ||= Array if block

spec/grape/validations_spec.rb

@@ -47,6 +47,44 @@ def app
       end
     end
 
+    context 'optional using Grape::Entity documentation' do
+      def define_optional_using
+        documentation = { field_a: { type: String }, field_b: { type: String } }
+        subject.params do
+          optional :all, using: documentation
+        end
+      end
+      before do
+        define_optional_using
+        subject.get '/optional' do
+          'optional with using works'
+        end
+      end
+
+      it 'adds entity documentation to declared params' do
+        define_optional_using
+        expect(subject.route_setting(:declared_params)).to eq([:field_a, :field_b])
+      end
+
+      it 'works when field_a and field_b are not present' do
+        get '/optional'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('optional with using works')
+      end
+
+      it 'works when field_a is present' do
+        get '/optional', field_a: 'woof'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('optional with using works')
+      end
+
+      it 'works when field_b is present' do
+        get '/optional', field_b: 'woof'
+        expect(last_response.status).to eq(200)
+        expect(last_response.body).to eq('optional with using works')
+      end
+    end
+
     context 'required' do
       before do
         subject.params do