Merge pull request #572 from johnallen3d/parameter-documentation

Added documentation support to parameters

CHANGELOG.md

@@ -16,6 +16,7 @@ Next Release
 * [#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).
 * [#560](https://github.com/intridea/grape/pull/560): Use `Grape::Entity` documentation to define required and optional parameters with `requires using:` - [@reynardmh](https://github.com/reynardmh).
+* [#572](https://github.com/intridea/grape/pull/572): Added `documentation` support to `requires`, `optional` and `group` parameters - [@johnallen3d](https://github.com/johnallen3d).
 * Your contribution here.
 
 #### Fixes

README.md

@@ -637,6 +637,17 @@ class API < Grape::API
 end
 ```
 
+## Parameter Documentation
+
+You can attach additional documentation to `params` using a `documentation` hash.
+
+```ruby
+params do
+  optional :first_name, type: String, documentation: { example: 'Jim' }
+  requires :last_name, type: String, documentation: { example: 'Smith' }
+end
+```
+
 ## Cookies
 
 You can set, get and delete your cookies very simply using `cookies` method.

lib/grape/validations.rb

@@ -244,6 +244,8 @@ def validates(attrs, validations)
           raise Grape::Exceptions::IncompatibleOptionValues.new(:type, coerce_type, :values, values)
         end
 
+        doc_attrs[:documentation] = validations.delete(:documentation) if validations.key?(:documentation)
+
         full_attrs = attrs.collect { |name| { name: name, full_name: full_name(name) } }
         @api.document_attribute(full_attrs, doc_attrs)
 

spec/grape/validations_spec.rb

@@ -823,5 +823,19 @@ module SharedParams
 
       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
+
+        subject.routes.first.route_params['first_name'][:documentation].should eq(documentation)
+      end
+    end
   end
 end