introduced new desc dsl with a block instead of option Hash

Dieter Späth · Dieter Späth · commit 0e13e9a06e66 · 2014-09-29T15:08:17.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,7 @@
 * Your contribution here.
 * [#745](https://github.com/intridea/grape/pull/745): Removed `atom+xml`, `rss+xml`, and `jsonapi` content-types - [@akabraham](https://github.com/akabraham).
 * [#745](https://github.com/intridea/grape/pull/745): Added `:binary, application/octet-stream` content-type - [@akabraham](https://github.com/akabraham).
+* [#757](https://github.com/intridea/grape/pull/757): Changed `desc` can now be used with a block syntax - [@dspaeth-faber](https://github.com/dspaeth-faber).
 
 0.9.0 (8/27/2014)
 =================
diff --git a/README.md b/README.md
@@ -358,12 +358,34 @@ version 'v1', using: :param, parameter: "v"
 You can add a description to API methods and namespaces.
 
 ```ruby
-desc "Returns your public timeline."
+desc "Returns your public timeline." do
+  detail 'more details'
+  params  API::Entities::Status.documentation
+  success API::Entities::Entity
+  failure [[401, 'Unauthorized', "Entities::Error"]]
+  named 'My named route'
+  headers [XAuthToken: {
+             description: 'Valdates your identity',
+             required: true
+           },
+           XOptionalHeader: {
+             description: 'Not really needed',
+            required: false
+           }
+          ]
+end
 get :public_timeline do
   Status.limit(20)
 end
 ```
 
+* `detail`: A more enhanced description
+* `params`: Define parameters directly from an `Entity` 
+* `success`: (former entity) The `Entity` to be used to present by default this route
+* `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
+
 ## Parameters
 
 Request parameters are available through the `params` hash object. This includes `GET`, `POST`
@@ -1019,14 +1041,18 @@ end
 The following example specifies the entity to use in the `http_codes` definition.
 
 ```
-desc 'My Route', http_codes: [[408, 'Unauthorized', API::Error]]
+desc 'My Route' do
+ failure [[408, 'Unauthorized', API::Error]]
+end
 error!({ message: 'Unauthorized' }, 408)
 ```
 
 The following example specifies the presented entity explicitly in the error message.
 
 ```ruby
-desc 'My Route', http_codes: [[408, 'Unauthorized']]
+desc 'My Route' do
+ failure [[408, 'Unauthorized']]
+end
 error!({ message: 'Unauthorized', with: API::Error }, 408)
 ```
 
@@ -1462,9 +1488,9 @@ module API
   class Statuses < Grape::API
     version 'v1'
 
-    desc 'Statuses index', {
+    desc 'Statuses index' do
       params: API::Entities::Status.documentation
-    }
+    end
     get '/statuses' do
       statuses = Status.all
       type = current_user.admin? ? :full : :default
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -13,6 +13,58 @@ The following content-types have been removed:
 
 This is because they have never been properly supported.
 
+
+#### Changes to desc
+
+New block syntax:
+
+Former:
+
+```ruby
+  desc "some descs",
+           detail: 'more details',
+           entity: API::Entities::Entity,
+           params;  API::Entities::Status.documentation,
+           named: 'a name',
+           headers :[XAuthToken: {
+                description: 'Valdates your identity',
+                required: true
+              }
+  get nil, http_codes: [
+            [401, 'Unauthorized', API::Entities::BaseError],
+            [404, 'not found', API::Entities::Error]
+  
+  ] do
+  
+```
+
+Now:
+
+```ruby
+
+desc "some descs" do
+  detail 'more details'
+  params  API::Entities::Status.documentation
+  success API::Entities::Entity
+  failure [
+            [401, 'Unauthorized', API::Entities::BaseError],
+            [404, 'not found', API::Entities::Error]  
+          ]
+    named 'a name'
+    headers [XAuthToken: {
+               description: 'Valdates your identity',
+               required: true
+             },
+             XOptionalHeader: {
+               description: 'Not really needed',
+              required: false
+             }
+            ]
+end
+  
+
+```
+
 ### Upgrading to >= 0.9.0 
 
 #### Changes in Authentication
diff --git a/lib/grape.rb b/lib/grape.rb
@@ -104,6 +104,7 @@ module Util
     autoload :InheritableValues, 'grape/util/inheritable_values'
     autoload :StackableValues,   'grape/util/stackable_values'
     autoload :InheritableSetting, 'grape/util/inheritable_setting'
+    autoload :StrictHashConfiguration, 'grape/util/strict_hash_configuration'
   end
 
   module DSL
diff --git a/lib/grape/dsl/configuration.rb b/lib/grape/dsl/configuration.rb
@@ -19,9 +19,22 @@ def logger(logger = nil)
         end
 
         # Add a description to the next namespace or function.
-        def desc(description, options = {})
-          namespace_setting :description, options.merge(description: description)
-          route_setting :description, options.merge(description: description)
+        def desc(description, options = {}, &config_block)
+          if block_given?
+            config_class = Grape::DSL::Configuration.desc_container
+
+            config_class.configure do
+              description description
+            end
+
+            config_class.configure(&config_block)
+            options = config_class.settings
+          else
+            options = options.merge(description: description)
+          end
+
+          namespace_setting :description, options
+          route_setting :description, options
         end
       end
 
@@ -31,6 +44,29 @@ def stacked_hash_to_hash(settings)
         return nil if settings.nil? || settings.blank?
         settings.each_with_object(ActiveSupport::OrderedHash.new) { |value, result| result.deep_merge!(value) }
       end
+
+      def desc_container
+        Module.new do
+          include Grape::Util::StrictHashConfiguration.module(
+                      :description,
+                      :detail,
+                      :params,
+                      :entity,
+                      :http_codes,
+                      :named,
+                      :headers
+          )
+
+          def config_context.success(*args)
+            entity(*args)
+          end
+
+          def config_context.failure(*args)
+            http_codes(*args)
+          end
+
+        end
+      end
     end
   end
 end
diff --git a/lib/grape/util/strict_hash_configuration.rb b/lib/grape/util/strict_hash_configuration.rb
@@ -0,0 +1,109 @@
+module Grape
+  module Util
+    module StrictHashConfiguration
+      extend ActiveSupport::Concern
+
+      module DSL
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+          def settings
+            config_context.to_hash
+          end
+
+          def configure(&block)
+            config_context.instance_exec(&block)
+          end
+        end
+      end
+
+      class SettingsContainer
+        def initialize
+          @settings = {}
+          @contexts = {}
+        end
+
+        def to_hash
+          @settings.to_hash
+        end
+      end
+
+      def self.config_class(*args)
+        new_config_class = Class.new(SettingsContainer)
+
+        args.each do |setting_name|
+          if setting_name.respond_to? :values
+            nested_settings_methods(setting_name, new_config_class)
+          else
+            simple_settings_methods(setting_name, new_config_class)
+          end
+        end
+
+        new_config_class
+      end
+
+      def self.simple_settings_methods(setting_name, new_config_class)
+        setting_name_sym = setting_name.to_sym
+        new_config_class.class_eval do
+          define_method setting_name do |new_value|
+            @settings[setting_name_sym] = new_value
+          end
+        end
+      end
+
+      def self.nested_settings_methods(setting_name, new_config_class)
+        new_config_class.class_eval do
+          setting_name.each_pair do |key, value|
+            define_method "#{key}_context" do
+              @contexts[key] ||= Grape::Util::StrictHashConfiguration.config_class(*value).new
+            end
+
+            define_method key do |&block|
+              send("#{key}_context").instance_exec(&block)
+            end
+          end
+
+          define_method 'to_hash' do
+            merge_hash = setting_name.keys.each_with_object({}) { |k, hash| hash[k] = send("#{k}_context").to_hash }
+
+            @settings.to_hash.merge(
+              merge_hash
+            )
+          end
+
+        end
+      end
+
+      def self.module(*args)
+        new_module = Module.new do
+          extend ActiveSupport::Concern
+          include DSL
+        end
+
+        new_module.tap do |mod|
+
+          class_mod = create_class_mod(args)
+
+          mod.const_set(:ClassMethods, class_mod)
+
+        end
+      end
+
+      def self.create_class_mod(args)
+        new_module = Module.new do
+          def config_context
+            @config_context ||= config_class.new
+          end
+        end
+
+        new_module.tap do |class_mod|
+          new_config_class = config_class(*args)
+
+          class_mod.send(:define_method, :config_class) do
+            @config_context ||= new_config_class
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/spec/grape/dsl/configuration_spec.rb b/spec/grape/dsl/configuration_spec.rb
@@ -24,10 +24,51 @@ class Dummy
 
       describe '.desc' do
         it 'sets a description' do
+          desc_text = 'The description'
           options = { message: 'none' }
-          subject.desc options
-          expect(subject.namespace_setting(:description)).to eq(description: options)
-          expect(subject.route_setting(:description)).to eq(description: options)
+          subject.desc desc_text, options
+          expect(subject.namespace_setting(:description)).to eq(options.merge(description: desc_text))
+          expect(subject.route_setting(:description)).to eq(options.merge(description: desc_text))
+        end
+
+        it 'can be set with a block' do
+          expected_options = {
+            description: 'The description',
+            detail: 'more details',
+            params: { first: :param },
+            entity: Object,
+            http_codes: [[401, 'Unauthorized', "Entities::Error"]],
+            named: "My named route",
+            headers: [XAuthToken: {
+              description: 'Valdates your identity',
+              required: true
+            },
+                      XOptionalHeader: {
+                        description: 'Not really needed',
+                        required: false
+                      }
+              ]
+          }
+
+          subject.desc 'The description' do
+            detail 'more details'
+            params(first: :param)
+            success Object
+            failure [[401, 'Unauthorized', "Entities::Error"]]
+            named 'My named route'
+            headers [XAuthToken: {
+              description: 'Valdates your identity',
+              required: true
+            },
+                     XOptionalHeader: {
+                       description: 'Not really needed',
+                       required: false
+                     }
+            ]
+          end
+
+          expect(subject.namespace_setting(:description)).to eq(expected_options)
+          expect(subject.route_setting(:description)).to eq(expected_options)
         end
       end
 
diff --git a/spec/grape/util/strict_hash_configuration_spec.rb b/spec/grape/util/strict_hash_configuration_spec.rb
