Support more options in desc block

Fix #1789. Support `summary`, `hidden`, `deprecated`, `is_array`, `nickname`, `produces`, `consumes`, `tags` options in desc block.
ruby-grape · Sep 15, 2018 · 7858d71 · 7858d71
1 parent 41b7519
commit 7858d71
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -446,10 +446,13 @@ version 'v1', using: :param, parameter: 'v'
 
 ## Describing Methods
 
-You can add a description to API methods and namespaces.
+You can add a description to API methods and namespaces. The description would be used by [grape-swagger][grape-swagger] to generate swagger compliant documentation.
+
+Note: Description block is only for documentation and won't affects API behavior.
 
 ```ruby
 desc 'Returns your public timeline.' do
+  summary 'summary'
   detail 'more details'
   params  API::Entities::Status.documentation
   success API::Entities::Entity
@@ -463,7 +466,13 @@ desc 'Returns your public timeline.' do
             description: 'Not really needed',
             required: false
           }
-
+  hidden false
+  deprecated false
+  is_array true
+  nickname 'nickname'
+  produces ['array', 'of', 'mime_types']
+  consumes ['array', 'of', 'mime_types']
+  tags ['tag1', 'tag2']
 end
 get :public_timeline do
   Status.limit(20)
@@ -476,6 +485,9 @@ end
 * `failure`: (former http_codes) A definition of the used failure HTTP Codes and Entities
 * `named`: A helper to give a route a name and find it with this name in the documentation Hash
 * `headers`: A definition of the used Headers
+* Other options can be found in [grape-swagger][grape-swagger]
+
+[grape-swagger]: https://github.com/ruby-grape/grape-swagger
 
 ## Parameters
 

diff --git a/lib/grape/dsl/desc.rb b/lib/grape/dsl/desc.rb
@@ -78,13 +78,21 @@ def unset_description_field(field)
       def desc_container
         Module.new do
           include Grape::Util::StrictHashConfiguration.module(
+            :summary,
             :description,
             :detail,
             :params,
             :entity,
             :http_codes,
             :named,
-            :headers
+            :headers,
+            :hidden,
+            :deprecated,
+            :is_array,
+            :nickname,
+            :produces,
+            :consumes,
+            :tags
           )
 
           def config_context.success(*args)

diff --git a/spec/grape/dsl/desc_spec.rb b/spec/grape/dsl/desc_spec.rb
@@ -21,6 +21,7 @@ class Dummy
 
         it 'can be set with a block' do
           expected_options = {
+            summary: 'summary',
             description: 'The description',
             detail: 'more details',
             params: { first: :param },
@@ -34,10 +35,18 @@ class Dummy
                       XOptionalHeader: {
                         description: 'Not really needed',
                         required: false
-                      }]
+                      }],
+            hidden: false,
+            deprecated: false,
+            is_array: true,
+            nickname: 'nickname',
+            produces: ['array', 'of', 'mime_types'],
+            consumes: ['array', 'of', 'mime_types'],
+            tags: ['tag1', 'tag2']
           }
 
           subject.desc 'The description' do
+            summary 'summary'
             detail 'more details'
             params(first: :param)
             success Object
@@ -51,6 +60,13 @@ class Dummy
                        description: 'Not really needed',
                        required: false
                      }]
+            hidden false
+            deprecated false
+            is_array true
+            nickname 'nickname'
+            produces ['array', 'of', 'mime_types']
+            consumes ['array', 'of', 'mime_types']
+            tags ['tag1', 'tag2']
           end
 
           expect(subject.namespace_setting(:description)).to eq(expected_options)