Support more options in desc block (#1791)

* Support more options in desc blockFix #1789.Support `summary`, `hidden`, `deprecated`, `is_array`, `nickname`,`produces`, `consumes`, `tags` options in desc block. * Fix rubocop and update CHANGELOG * Refine documentation [ci skip] Add real mime type in README. Add options documentation in `desc`.
ruby-grape · Sep 16, 2018 · 35b432c · 35b432c
1 parent 41b7519
commit 35b432c
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,7 @@
 #### Features
 
 * Your contribution here.
+* [#1791](https://github.com/ruby-grape/grape/pull/1791): Support `summary`, `hidden`, `deprecated`, `is_array`, `nickname`, `produces`, `consumes`, `tags` options in `desc` block - [@darren987469](https://github.com/darren987469).
 
 #### Fixes
 

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 ['application/json']
+  consumes ['application/json']
+  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
@@ -4,6 +4,7 @@ module Desc
       include Grape::DSL::Settings
 
       # Add a description to the next namespace or function.
+      # @option options :summary [String] summary for this endpoint
       # @param description [String] descriptive string for this endpoint
       #   or namespace
       # @param options [Hash] other properties you can set to describe the
@@ -17,6 +18,13 @@ module Desc
       #   endpoint may return, with their meanings, in a 2d array
       # @option options :named [String] a specific name to help find this route
       # @option options :headers [Hash] HTTP headers this method can accept
+      # @option options :hidden [Boolean] hide the endpoint or not
+      # @option options :deprecated [Boolean] deprecate the endpoint or not
+      # @option options :is_array [Boolean] response entity is array or not
+      # @option options :nickname [String] nickname of the endpoint
+      # @option options :produces [Array[String]] a list of MIME types the endpoint produce
+      # @option options :consumes [Array[String]] a list of MIME types the endpoint consume
+      # @option options :tags [Array[String]] a list of tags
       # @yield a block yielding an instance context with methods mapping to
       #   each of the above, except that :entity is also aliased as #success
       #   and :http_codes is aliased as #failure.
@@ -78,13 +86,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: %w[array of mime_types],
+            consumes: %w[array of mime_types],
+            tags: %w[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 %w[array of mime_types]
+            consumes %w[array of mime_types]
+            tags %w[tag1 tag2]
           end
 
           expect(subject.namespace_setting(:description)).to eq(expected_options)