From 4516cd11f5626d7f6c4814385bef79784c88ee26 Mon Sep 17 00:00:00 2001
From: John Allen <john@threedogconsulting.com>
Date: Tue, 4 Feb 2014 18:07:44 -0500
Subject: [PATCH] Added documentation support to parameters

---
 CHANGELOG.md                   |  1 +
 README.md                      | 11 +++++++++++
 lib/grape/validations.rb       |  2 ++
 spec/grape/validations_spec.rb | 14 ++++++++++++++
 4 files changed, 28 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0359498688..58d2f3c179 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/README.md b/README.md
index a20de20e4e..3ed6a6e602 100644
--- a/README.md
+++ b/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.
diff --git a/lib/grape/validations.rb b/lib/grape/validations.rb
index 84fad680b6..a1ef0e3af1 100644
--- a/lib/grape/validations.rb
+++ b/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)
 
diff --git a/spec/grape/validations_spec.rb b/spec/grape/validations_spec.rb
index 1b923e9499..503eedcbfd 100644
--- a/spec/grape/validations_spec.rb
+++ b/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