grape 0.12.0 → 0.14.0

data/lib/grape/dsl/configuration.rb

@@ -10,6 +10,9 @@ module Grape
 
         include Grape::DSL::Settings
 
+        # Set or retrive the configured logger. If none was configured, this
+        # method will create a new one, logging to stdout.
+        # @param logger [Object] the new logger to use
         def logger(logger = nil)
           if logger
             global_setting(:logger, logger)
@@ -19,6 +22,39 @@ module Grape
         end
 
         # Add a description to the next namespace or function.
+        # @param description [String] descriptive string for this endpoint
+        #   or namespace
+        # @param options [Hash] other properties you can set to describe the
+        #   endpoint or namespace. Optional.
+        # @option options :detail [String] additional detail about this endpoint
+        # @option options :params [Hash] param types and info. normally, you set
+        #   these via the `params` dsl method.
+        # @option options :entity [Grape::Entity] the entity returned upon a
+        #   successful call to this action
+        # @option options :http_codes [Array[Array]] possible HTTP codes this
+        #   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
+        # @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.
+        #
+        # @example
+        #
+        #     desc 'create a user'
+        #     post '/users' do
+        #       # ...
+        #     end
+        #
+        #     desc 'find a user' do
+        #       detail 'locates the user from the given user ID'
+        #       failure [ [404, 'Couldn\'t find the given user' ] ]
+        #       success User::Entity
+        #     end
+        #     get '/user/:id' do
+        #       # ...
+        #     end
+        #
         def desc(description, options = {}, &config_block)
           if block_given?
             config_class = Grape::DSL::Configuration.desc_container
@@ -28,6 +64,9 @@ module Grape
             end
 
             config_class.configure(&config_block)
+            unless options.empty?
+              warn '[DEPRECATION] Passing a options hash and a block to `desc` is deprecated. Move all hash options to block.'
+            end
             options = config_class.settings
           else
             options = options.merge(description: description)
@@ -36,15 +75,33 @@ module Grape
           namespace_setting :description, options
           route_setting :description, options
         end
+
+        def description_field(field, value = nil)
+          if value
+            description = route_setting(:description)
+            description ||= route_setting(:description, {})
+            description[field] = value
+          else
+            description = route_setting(:description)
+            description[field] if description
+          end
+        end
+
+        def unset_description_field(field)
+          description = route_setting(:description)
+          description.delete(field) if description
+        end
       end
 
       module_function
 
+      # Merge multiple layers of settings into one hash.
       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) }
+        return if settings.blank?
+        settings.each_with_object({}) { |value, result| result.deep_merge!(value) }
       end
 
+      # Returns an object which configures itself via an instance-context DSL.
       def desc_container
         Module.new do
           include Grape::Util::StrictHashConfiguration.module(

data/lib/grape/dsl/helpers.rb

@@ -29,6 +29,7 @@ module Grape
         def helpers(new_mod = nil, &block)
           if block_given? || new_mod
             mod = new_mod || Module.new
+            define_boolean_in_mod(mod)
             if new_mod
               inject_api_helpers_to_mod(new_mod) if new_mod.is_a?(BaseHelper)
             end
@@ -51,6 +52,11 @@ module Grape
 
         protected
 
+        def define_boolean_in_mod(mod)
+          return if defined? mod::Boolean
+          mod.const_set('Boolean', Virtus::Attribute::Boolean)
+        end
+
         def inject_api_helpers_to_mod(mod, &_block)
           mod.extend(BaseHelper)
           yield if block_given?
@@ -75,9 +81,8 @@ module Grape
         protected
 
         def process_named_params
-          if @named_params && @named_params.any?
-            api.namespace_stackable(:named_params, @named_params)
-          end
+          return unless @named_params && @named_params.any?
+          api.namespace_stackable(:named_params, @named_params)
         end
       end
     end

data/lib/grape/dsl/inside_route.rb

@@ -6,57 +6,74 @@ module Grape
       extend ActiveSupport::Concern
       include Grape::DSL::Settings
 
-      # A filtering method that will return a hash
-      # consisting only of keys that have been declared by a
-      # `params` statement against the current/target endpoint or parent
-      # namespaces.
-      #
-      # @param params [Hash] The initial hash to filter. Usually this will just be `params`
-      # @param options [Hash] Can pass `:include_missing`, `:stringify` and `:include_parent_namespaces`
-      # options. `:include_parent_namespaces` defaults to true, hence must be set to false if
-      # you want only to return params declared against the current/target endpoint.
-      def declared(params, options = {}, declared_params = nil)
-        options[:include_missing] = true unless options.key?(:include_missing)
-        options[:include_parent_namespaces] = true unless options.key?(:include_parent_namespaces)
-
-        if declared_params.nil?
-          declared_params = (!options[:include_parent_namespaces] ? route_setting(:declared_params) :
-              (route_setting(:saved_declared_params) || [])).flatten(1) || []
-        end
+      # Denotes a situation where a DSL method has been invoked in a
+      # filter which it should not yet be available in
+      class MethodNotYetAvailable < StandardError; end
 
-        unless declared_params
-          fail ArgumentError, 'Tried to filter for declared parameters but none exist.'
-        end
+      # @param type [Symbol] The type of filter for which evaluation has been
+      #   completed
+      # @return [Module] A module containing method overrides suitable for the
+      #   position in the filter evaluation sequence denoted by +type+.  This
+      #   defaults to an empty module if no overrides are defined for the given
+      #   filter +type+.
+      def self.post_filter_methods(type)
+        @post_filter_modules ||= { before: PostBeforeFilter }
+        @post_filter_modules[type]
+      end
 
-        if params.is_a? Array
-          params.map do |param|
-            declared(param || {}, options, declared_params)
-          end
-        else
-          declared_params.inject(Hashie::Mash.new) do |hash, key|
-            key = { key => nil } unless key.is_a? Hash
+      # Methods which should not be available in filters until the before filter
+      # has completed
+      module PostBeforeFilter
+        def declared(params, options = {}, declared_params = nil)
+          options = options.reverse_merge(include_missing: true, include_parent_namespaces: true)
 
-            key.each_pair do |parent, children|
-              output_key = options[:stringify] ? parent.to_s : parent.to_sym
+          declared_params ||= (!options[:include_parent_namespaces] ? route_setting(:declared_params) : (route_setting(:saved_declared_params) || [])).flatten(1) || []
 
-              next unless options[:include_missing] || params.key?(parent)
+          fail ArgumentError, 'Tried to filter for declared parameters but none exist.' unless declared_params
 
-              hash[output_key] = if children
-                                   children_params = params[parent] || (children.is_a?(Array) ? [] : {})
-                                   declared(children_params, options, Array(children))
-                                 else
-                                   params[parent]
-                                 end
+          if params.is_a? Array
+            params.map do |param|
+              declared(param || {}, options, declared_params)
             end
+          else
+            declared_params.each_with_object(Hashie::Mash.new) do |key, hash|
+              key = { key => nil } unless key.is_a? Hash
+
+              key.each_pair do |parent, children|
+                output_key = options[:stringify] ? parent.to_s : parent.to_sym
+
+                next unless options[:include_missing] || params.key?(parent)
 
-            hash
+                hash[output_key] = if children
+                                     children_params = params[parent] || (children.is_a?(Array) ? [] : {})
+                                     declared(children_params, options, Array(children))
+                                   else
+                                     params[parent]
+                                   end
+              end
+            end
           end
         end
       end
 
+      # A filtering method that will return a hash
+      # consisting only of keys that have been declared by a
+      # `params` statement against the current/target endpoint or parent
+      # namespaces.
+      #
+      # @see +PostBeforeFilter#declared+
+      #
+      # @param params [Hash] The initial hash to filter. Usually this will just be `params`
+      # @param options [Hash] Can pass `:include_missing`, `:stringify` and `:include_parent_namespaces`
+      # options. `:include_parent_namespaces` defaults to true, hence must be set to false if
+      # you want only to return params declared against the current/target endpoint.
+      def declared(*)
+        fail MethodNotYetAvailable, '#declared is not available prior to parameter validation.'
+      end
+
       # The API version as specified in the URL.
       def version
-        env['api.version']
+        env[Grape::Env::API_VERSION]
       end
 
       # End the request and display an error to the
@@ -74,19 +91,25 @@ module Grape
       # @param url [String] The url to be redirect.
       # @param options [Hash] The options used when redirect.
       #                       :permanent, default false.
+      #                       :body, default a short message including the URL.
       def redirect(url, options = {})
-        merged_options = { permanent: false }.merge(options)
-        if merged_options[:permanent]
+        permanent = options.fetch(:permanent, false)
+        body_message = options.fetch(:body, nil)
+        if permanent
           status 301
+          body_message ||= "This resource has been moved permanently to #{url}."
         else
           if env[Grape::Http::Headers::HTTP_VERSION] == 'HTTP/1.1' && request.request_method.to_s.upcase != Grape::Http::Headers::GET
             status 303
+            body_message ||= "An alternate resource is located at #{url}."
           else
             status 302
+            body_message ||= "This resource has been moved temporarily to #{url}."
           end
         end
         header 'Location', url
-        body ''
+        content_type 'text/plain'
+        body body_message
       end
 
       # Set or retrieve the HTTP status code.
@@ -177,12 +200,34 @@ module Grape
       #   GET /file # => "contents of file"
       def file(value = nil)
         if value
-          @file = value
+          @file = Grape::Util::FileResponse.new(value)
         else
           @file
         end
       end
 
+      # Allows you to define the response as a streamable object.
+      #
+      # If Content-Length and Transfer-Encoding are blank (among other conditions),
+      # Rack assumes this response can be streamed in chunks.
+      #
+      # @example
+      #   get '/stream' do
+      #     stream FileStreamer.new(...)
+      #   end
+      #
+      #   GET /stream # => "chunked contents of file"
+      #
+      # See:
+      # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/chunked.rb
+      # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/etag.rb
+      def stream(value = nil)
+        header 'Content-Length', nil
+        header 'Transfer-Encoding', nil
+        header 'Cache-Control', 'no-cache' # Skips ETag generation (reading the response up front)
+        file(value)
+      end
+
       # Allows you to make use of Grape Entities by setting
       # the response body to the serializable hash of the
       # entity provided in the `:with` option. This has the
@@ -219,7 +264,7 @@ module Grape
         if key
           representation = (@body || {}).merge(key => representation)
         elsif entity_class.present? && @body
-          fail ArgumentError, "Representation of type #{representation.class} cannot be merged." unless representation.respond_to?('merge')
+          fail ArgumentError, "Representation of type #{representation.class} cannot be merged." unless representation.respond_to?(:merge)
           representation = @body.merge(representation)
         end
 
@@ -235,9 +280,17 @@ module Grape
       #     route.route_description
       #   end
       def route
-        env['rack.routing_args'][:route_info]
+        env[Grape::Env::RACK_ROUTING_ARGS][:route_info]
       end
 
+      # Attempt to locate the Entity class for a given object, if not given
+      # explicitly. This is done by looking for the presence of Klass::Entity,
+      # where Klass is the class of the `object` parameter, or one of its
+      # ancestors.
+      # @param object [Object] the object to locate the Entity class for
+      # @param options [Hash]
+      # @option options :with [Class] the explicit entity class to use
+      # @return [Class] the located Entity class, or nil if none is found
       def entity_class_for_obj(object, options)
         entity_class = options.delete(:with)
 
@@ -259,9 +312,11 @@ module Grape
         entity_class
       end
 
+      # @return the representation of the given object as done through
+      #   the given entity_class.
       def entity_representation_for(entity_class, object, options)
         embeds = { env: env }
-        embeds[:version] = env['api.version'] if env['api.version']
+        embeds[:version] = env[Grape::Env::API_VERSION] if env[Grape::Env::API_VERSION]
         entity_class.represent(object, embeds.merge(options))
       end
     end

data/lib/grape/dsl/parameters.rb

@@ -2,6 +2,9 @@ require 'active_support/concern'
 
 module Grape
   module DSL
+    # Defines DSL methods, meant to be applied to a ParamsScope, which define
+    # and describe the parameters accepted by an endpoint, or all endpoints
+    # within a namespace.
     module Parameters
       extend ActiveSupport::Concern
 
@@ -28,7 +31,7 @@ module Grape
       #     end
       def use(*names)
         named_params = Grape::DSL::Configuration.stacked_hash_to_hash(@api.namespace_stackable(:named_params)) || {}
-        options = names.last.is_a?(Hash) ? names.pop : {}
+        options = names.extract_options!
         names.each do |name|
           params_block = named_params.fetch(name) do
             fail "Params :#{name} not found!"
@@ -39,10 +42,62 @@ module Grape
       alias_method :use_scope, :use
       alias_method :includes, :use
 
+      # Require one or more parameters for the current endpoint.
+      #
+      # @param attrs list of parameter names, or, if :using is
+      #   passed as an option, which keys to include (:all or :none) from
+      #   the :using hash. The last key can be a hash, which specifies
+      #   options for the parameters
+      # @option attrs :type [Class] the type to coerce this parameter to before
+      #   passing it to the endpoint. See {Grape::Validations::Types} for a list of
+      #   types that are supported automatically. Custom classes may be used
+      #   where they define a class-level `::parse` method, or in conjunction
+      #   with the `:coerce_with` parameter. `JSON` may be supplied to denote
+      #   `JSON`-formatted objects or arrays of objects. `Array[JSON]` accepts
+      #   the same values as `JSON` but will wrap single objects in an `Array`.
+      # @option attrs :types [Array<Class>] may be supplied in place of +:type+
+      #   to declare an attribute that has multiple allowed types. See
+      #   {Validations::Types::MultipleTypeCoercer} for more details on coercion
+      #   and validation rules for variant-type parameters.
+      # @option attrs :desc [String] description to document this parameter
+      # @option attrs :default [Object] default value, if parameter is optional
+      # @option attrs :values [Array] permissable values for this field. If any
+      #   other value is given, it will be handled as a validation error
+      # @option attrs :using [Hash[Symbol => Hash]] a hash defining keys and
+      #   options, like that returned by {Grape::Entity#documentation}. The value
+      #   of each key is an options hash accepting the same parameters
+      # @option attrs :except [Array[Symbol]] a list of keys to exclude from
+      #   the :using Hash. The meaning of this depends on if :all or :none was
+      #   passed; :all + :except will make the :except fields optional, whereas
+      #   :none + :except will make the :except fields required
+      # @option attrs :coerce_with [#parse, #call] method to be used when coercing
+      #   the parameter to the type named by `attrs[:type]`. Any class or object
+      #   that defines `::parse` or `::call` may be used.
+      #
+      # @example
+      #
+      #     params do
+      #       # Basic usage: require a parameter of a certain type
+      #       requires :user_id, type: Integer
+      #
+      #       # You don't need to specify type; String is default
+      #       requires :foo
+      #
+      #       # Multiple params can be specified at once if they share
+      #       # the same options.
+      #       requires :x, :y, :z, type: Date
+      #
+      #       # Nested parameters can be handled as hashes. You must
+      #       # pass in a block, within which you can use any of the
+      #       # parameters DSL methods.
+      #       requires :user, type: Hash do
+      #         requires :name, type: String
+      #       end
+      #     end
       def requires(*attrs, &block)
         orig_attrs = attrs.clone
 
-        opts = attrs.last.is_a?(Hash) ? attrs.pop.clone : {}
+        opts = attrs.extract_options!.clone
         opts[:presence] = true
 
         if opts[:using]
@@ -50,15 +105,18 @@ module Grape
         else
           validate_attributes(attrs, opts, &block)
 
-          block_given? ? new_scope(orig_attrs, &block) :
-              push_declared_params(attrs)
+          block_given? ? new_scope(orig_attrs, &block) : push_declared_params(attrs)
         end
       end
 
+      # Allow, but don't require, one or more parameters for the current
+      #   endpoint.
+      # @param (see #requires)
+      # @option (see #requires)
       def optional(*attrs, &block)
         orig_attrs = attrs.clone
 
-        opts = attrs.last.is_a?(Hash) ? attrs.pop.clone : {}
+        opts = attrs.extract_options!.clone
         type = opts[:type]
 
         # check type for optional parameter group
@@ -72,29 +130,60 @@ module Grape
         else
           validate_attributes(attrs, opts, &block)
 
-          block_given? ? new_scope(orig_attrs, true, &block) :
-              push_declared_params(attrs)
+          block_given? ? new_scope(orig_attrs, true, &block) : push_declared_params(attrs)
         end
       end
 
+      # Disallow the given parameters to be present in the same request.
+      # @param attrs [*Symbol] parameters to validate
       def mutually_exclusive(*attrs)
         validates(attrs, mutual_exclusion: true)
       end
 
+      # Require exactly one of the given parameters to be present.
+      # @param (see #mutually_exclusive)
       def exactly_one_of(*attrs)
         validates(attrs, exactly_one_of: true)
       end
 
+      # Require at least one of the given parameters to be present.
+      # @param (see #mutually_exclusive)
       def at_least_one_of(*attrs)
         validates(attrs, at_least_one_of: true)
       end
 
+      # Require that either all given params are present, or none are.
+      # @param (see #mutually_exclusive)
       def all_or_none_of(*attrs)
         validates(attrs, all_or_none_of: true)
       end
 
+      # Define a block of validations which should be applied if and only if
+      # the given parameter is present. The parameters are not nested.
+      # @param attr [Symbol] the parameter which, if present, triggers the
+      #   validations
+      # @raise Grape::Exceptions::UnknownParameter if `attr` has not been
+      #   defined in this scope yet
+      # @yield a parameter definition DSL
+      def given(attr, &block)
+        fail Grape::Exceptions::UnknownParameter.new(attr) unless declared_param?(attr)
+        new_lateral_scope(dependent_on: attr, &block)
+      end
+
+      # Test for whether a certain parameter has been defined in this params
+      # block yet.
+      # @return [Boolean] whether the parameter has been defined
+      def declared_param?(param)
+        # @declared_params also includes hashes of options and such, but those
+        # won't be flattened out.
+        @declared_params.flatten.include?(param)
+      end
+
       alias_method :group, :requires
 
+      # @param params [Hash] initial hash of parameters
+      # @return hash of parameters relevant for the current scope
+      # @api private
       def params(params)
         params = @parent.params(params) if @parent
         if @element

data/lib/grape/dsl/request_response.rb

@@ -104,7 +104,7 @@ module Grape
             handler = block
           end
 
-          options = args.last.is_a?(Hash) ? args.pop : {}
+          options = args.extract_options!
           handler ||= proc { options[:with] } if options.key?(:with)
 
           if args.include?(:all)

data/lib/grape/dsl/routing.rb

@@ -28,9 +28,8 @@ module Grape
         #
         def version(*args, &block)
           if args.any?
-            options = args.pop if args.last.is_a? Hash
-            options ||= {}
-            options = { using: :path }.merge(options)
+            options = args.extract_options!
+            options = options.reverse_merge(using: :path)
 
             fail Grape::Exceptions::MissingVendorOption.new if options[:using] == :header && !options.key?(:vendor)
 
@@ -76,7 +75,7 @@ module Grape
 
             if app.respond_to?(:inheritable_setting, true)
               mount_path = Rack::Mount::Utils.normalize_path(path)
-              app.top_level_setting.namespace_stackable[:mount_path] =  mount_path
+              app.top_level_setting.namespace_stackable[:mount_path] = mount_path
 
               app.inherit_settings(inheritable_setting)
 
@@ -135,6 +134,18 @@ module Grape
           end
         end
 
+        # Declare a "namespace", which prefixes all subordinate routes with its
+        # name. Any endpoints within a namespace, or group, resource, segment,
+        # etc., will share their parent context as well as any configuration
+        # done in the namespace context.
+        #
+        # @example
+        #
+        #     namespace :foo do
+        #       get 'bar' do
+        #         # defines the endpoint: GET /foo/bar
+        #       end
+        #     end
         def namespace(space = nil, options = {}, &block)
           if space || block_given?
             within_namespace do
@@ -162,6 +173,7 @@ module Grape
           @routes ||= prepare_routes
         end
 
+        # Remove all defined routes.
         def reset_routes!
           @routes = nil
         end
@@ -177,6 +189,7 @@ module Grape
           namespace(":#{param}", options, &block)
         end
 
+        # @return array of defined versions
         def versions
           @versions ||= []
         end