brainstem 1.1.1 → 1.3.0

data/lib/brainstem/api_docs/endpoint.rb

@@ -71,7 +71,7 @@ module Brainstem
       def <=>(other)
 
         # Any unordered routes are assigned an index of +ACTION_ORDER.count+.
-        ordered_actions_count = ACTION_ORDER.count
+        ordered_actions_count   = ACTION_ORDER.count
         own_action_priority     = ACTION_ORDER.index(action.to_s)       || ordered_actions_count
         other_action_priority   = ACTION_ORDER.index(other.action.to_s) || ordered_actions_count
 
@@ -120,32 +120,54 @@ module Brainstem
 
 
       #
-      # Returns a hash of all root-level params with values of an array of
-      # the parameters nested underneath, or +nil+ in the event they are
-      # root-level non-nested params.
+      # Returns a hash of all params nested under the specified root or
+      # parent fields along with their type, item type & children.
       #
-      # @return [Hash{Symbol => Array,NilClass}] root keys and the keys
-      #   nested under them, or nil if not a nested param.
+      # @return [Hash{Symbol => Hash}] root keys and their type info, item info & children
+      #   nested under them.
       #
-      def root_param_keys
-        @root_param_keys ||= begin
-          valid_params.to_h
-            .inject({}) do |hsh, (field_name, data)|
-              next hsh if data[:nodoc]
-
-              if data.has_key?(:root)
-                key  = data[:root].respond_to?(:call) ? data[:root].call(controller.const) : data[:root]
-                (hsh[key] ||= []) << field_name
-              else
-                hsh[field_name] = nil
+      def params_configuration_tree
+        @params_configuration_tree ||= begin
+          valid_params
+            .to_h
+            .deep_dup
+            .with_indifferent_access
+            .inject(ActiveSupport::HashWithIndifferentAccess.new) do |result, (field_name_proc, field_config)|
+
+            next result if field_config[:nodoc]
+
+            field_name = evaluate_field_name(field_name_proc)
+            if field_config.has_key?(:ancestors)
+              ancestors = field_config[:ancestors].map { |ancestor_key| evaluate_field_name(ancestor_key) }
+
+              parent = ancestors.inject(result) do |traversed_hash, ancestor_name|
+                traversed_hash[ancestor_name] ||= { :_config => { type: 'hash' } }
+                traversed_hash[ancestor_name]
               end
 
-              hsh
+              parent[field_name] = { :_config => field_config.except(:root, :ancestors) }
+            else
+              result[field_name] = { :_config => field_config }
             end
+
+            result
+          end
         end
       end
 
 
+      #
+      # Evaluate field name if proc and symbolize it.
+      #
+      def evaluate_field_name(field_name_or_proc)
+        return field_name_or_proc if field_name_or_proc.nil?
+
+        field_name = field_name_or_proc.respond_to?(:call) ? field_name_or_proc.call(controller.const) : field_name_or_proc
+        field_name.to_sym
+      end
+      alias_method :evaluate_root_name, :evaluate_field_name
+
+
       #
       # Retrieves the +presents+ settings.
       #

data/lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb

@@ -83,36 +83,34 @@ module Brainstem
           # Formats each parameter.
           #
           def format_params!
-            return unless endpoint.root_param_keys.any?
+            return unless endpoint.params_configuration_tree.any?
 
             output << md_h5("Valid Parameters")
             output << md_ul do
-              endpoint.root_param_keys.inject("") do |buff, (root_param_name, child_keys)|
-                if child_keys.nil?
-                  buff += parameter_with_indent_level(
-                    root_param_name,
-                    endpoint.valid_params[root_param_name],
-                    0
-                  )
-                else
-                  text = md_inline_code(root_param_name) + "\n"
-
-                  child_keys.each do |param_name|
-                    text += parameter_with_indent_level(
-                      param_name,
-                      endpoint.valid_params[param_name],
-                      1
-                    )
-                  end
-
-                  buff << md_li(text)
-                end
-
+              endpoint.params_configuration_tree.inject("") do |buff, (param_name, param_config)|
+                buff << format_param_tree!("", param_name, param_config)
                 buff
               end
             end
           end
 
+          #
+          # Formats the parent parameter and its children
+          #
+          def format_param_tree!(buffer, param_name, param_config, indentation = 0)
+            buffer += parameter_with_indent_level(
+              param_name,
+              param_config[:_config],
+              indentation
+            )
+
+            children = param_config.except(:_config) || []
+            children.each do |child_param_name, child_param_config|
+              buffer = format_param_tree!(buffer, child_param_name, child_param_config, indentation + 1)
+            end
+
+            buffer
+          end
 
           #
           # Formats a given parameter with a variable indent level. Useful for
@@ -120,11 +118,16 @@ module Brainstem
           #
           # @param [String] name the param name
           # @param [Hash] options information pertinent to the param
+          # @option [Boolean] options :required
           # @option [Boolean] options :legacy
           # @option [Boolean] options :recursive
           # @option [String,Symbol] options :only Deprecated: use +actions+
           #   block instead
           # @option [String] options :info the doc string for the param
+          # @option [String] options :type The type of the field.
+          #   e.g. string, integer, boolean, array, hash
+          # @option [String] options :item_type The type of the items in the field.
+          #   Ideally used when the type of the field is an array or hash.
           # @param [Integer] indent how many levels the output should be
           #   indented from normal
           #
@@ -132,10 +135,12 @@ module Brainstem
             options = options.dup
             text    = md_inline_code(title)
 
+            text += md_inline_type(options.delete(:type), options.delete(:item_type)) if options.has_key?(:type)
             text += " - #{options.delete(:info)}" if options.has_key?(:info)
 
             if options.keys.any?
               text += "\n"
+              text += md_li("Required: #{options[:required].to_s}",   indent + 1) if options.has_key?(:required) && options[:required]
               text += md_li("Legacy: #{options[:legacy].to_s}",       indent + 1) if options.has_key?(:legacy)
               text += md_li("Recursive: #{options[:recursive].to_s}", indent + 1) if options.has_key?(:recursive)
               text.chomp!

data/lib/brainstem/api_docs/formatters/markdown/helper.rb

@@ -69,6 +69,15 @@ module Brainstem
           def md_a(text, link)
             "[#{text}](#{link})"
           end
+
+
+          def md_inline_type(type, item_type = nil)
+            return "" if type.blank?
+
+            text = type.to_s.capitalize
+            text += "<#{item_type.to_s.capitalize}>" if item_type.present?
+            " (#{md_inline_code(text)})"
+          end
         end
       end
     end

data/lib/brainstem/api_docs/formatters/markdown/presenter_formatter.rb

@@ -62,7 +62,7 @@ module Brainstem
 
           def format_field_leaf(field, indent_level)
             text = md_inline_code(field.name.to_s)
-            text << " (#{md_inline_code(field.type.to_s.capitalize)})"
+            text << md_inline_type(field.type, field.options[:item_type])
 
             text << "\n"
             text << md_li(field.description, indent_level + 1) if field.description
@@ -85,9 +85,9 @@ module Brainstem
           def format_field_branch(branch, indent_level = 0)
             branch.inject("") do |buffer, (name, field)|
               if nested_field?(field)
-                sub_fields = md_inline_code(name.to_s) + "\n"
+                sub_fields = format_field_leaf(field, indent_level) + "\n"
                 sub_fields << format_field_branch(field.to_h, indent_level + 1)
-                buffer     += md_li(sub_fields, indent_level)
+                buffer += md_li(sub_fields, indent_level)
               else
                 buffer += md_li(format_field_leaf(field, indent_level), indent_level)
               end
@@ -96,7 +96,7 @@ module Brainstem
 
 
           def nested_field?(field)
-            !field.respond_to?(:options)
+            field.respond_to?(:configuration)
           end
 
 
@@ -120,10 +120,18 @@ module Brainstem
               output << md_ul do
                 presenter.valid_filters.inject("") do |buffer, (name, opts)|
                   text = md_inline_code(name)
+                  text << md_inline_type(opts[:type])
+
+                  if opts[:info] || opts[:items]
+                    description = opts[:info].to_s
+
+                    if opts[:items].present?
+                      description += "." unless description =~ /\.\s*\z/
+                      description += " Available values: #{opts[:items].join(', ')}."
+                    end
 
-                  if opts[:info]
                     text << "\n"
-                    text << md_li(opts[:info], 1)
+                    text << md_li(description, 1)
                     text.chomp!
                   end
 

data/lib/brainstem/api_docs/presenter.rb

@@ -105,12 +105,8 @@ module Brainstem
 
 
       def valid_fields(fields = configuration[:fields])
-        fields.to_h.reject do |k, v|
-          if nested_field?(v)
-            valid_fields_in(v).none?
-          else
-            invalid_field?(v)
-          end
+        fields.to_h.reject do |_, field|
+          invalid_field?(field) || (nested_field?(field) && valid_fields_in(field).none?)
         end
       end
       alias_method :valid_fields_in, :valid_fields
@@ -122,7 +118,7 @@ module Brainstem
 
 
       def nested_field?(field)
-        !field.respond_to?(:options)
+        field.respond_to?(:configuration)
       end
 
 

data/lib/brainstem/concerns/controller_dsl.rb

@@ -53,6 +53,14 @@ module Brainstem
         end
 
 
+        #
+        # Temporary implementation to track controllers that have been documented.
+        #
+        def documented!
+          configuration[brainstem_params_context][:documented] = true
+        end
+
+
         #
         # Specifies that the scope should not be documented. Setting this on
         # the default context will force the controller to be undocumented,
@@ -127,7 +135,7 @@ module Brainstem
         #   method accepting the controller constant and returning one
         #
         def model_params(root = Proc.new { |klass| klass.brainstem_model_name }, &block)
-          with_options({ root: root.is_a?(Symbol) ? root.to_s : root }, &block)
+          with_options(format_root_ancestry_options(root), &block)
         end
 
 
@@ -136,16 +144,37 @@ module Brainstem
         # the info sent with it.
         #
         # @param [Symbol] field_name the name of the param
+        # @param [String,Symbol] type the data type of the field. If not specified, will default to `string`.
         # @param [Hash] options
         # @option options [String] :info the documentation for the param
         # @option options [String,Symbol] :root if this is a nested param,
         #   under which param should it be nested?
         # @option options [Boolean] :nodoc should this param appear in the
         #   documentation?
+        # @option options [Boolean] :required if the param is required for
+        #   the endpoint
+        # @option options [String,Symbol] :item_type The data type of the items contained in a field.
+        #   Ideally used when the data type of the field is an `array`, `object` or `hash`.
         #
-        def valid(field_name, options = { nodoc: false })
+        def valid(field_name, type = nil, options = {}, &block)
           valid_params = configuration[brainstem_params_context][:valid_params]
-          valid_params[field_name.to_sym] = options
+          field_config = format_field_configuration(type, options, &block)
+
+          # Inherit `nodoc` attribute from parent
+          parent_key = (options[:ancestors] || []).reverse.first
+          field_config[:nodoc] = true if parent_key && valid_params[parent_key] && valid_params[parent_key][:nodoc]
+
+          # Rollup `required` attribute to ancestors if true
+          if field_config[:required]
+            (options[:ancestors] || []).reverse.each do |ancestor_key|
+              valid_params[ancestor_key][:required] = true if valid_params.has_key?(ancestor_key)
+            end
+          end
+
+          procified_field_name = format_field_name(field_name)
+          valid_params[procified_field_name] = field_config
+
+          with_options(format_field_ancestry_options(procified_field_name, field_config), &block) if block_given?
         end
 
 
@@ -209,8 +238,7 @@ module Brainstem
         #   be output in the documentation.
         #
         def description(text, options = { nodoc: false })
-          configuration[brainstem_params_context][:description] = \
-            options.merge(info: text)
+          configuration[brainstem_params_context][:description] = options.merge(info: text)
         end
 
 
@@ -230,12 +258,114 @@ module Brainstem
         #   output in the documentation.
         #
         def title(text, options = { nodoc: false })
-          configuration[brainstem_params_context][:title] = \
-            options.merge(info: text)
+          configuration[brainstem_params_context][:title] = options.merge(info: text)
+        end
+
+        #
+        # Converts the field name into a Proc.
+        #
+        # @param [String, Symbol, Proc] text The title to set
+        # @return [Proc]
+        #
+        def format_field_name(field_name_or_proc)
+          field_name_or_proc.respond_to?(:call) ? field_name_or_proc : Proc.new { field_name_or_proc.to_s }
+        end
+        alias_method :format_root_name, :format_field_name
+
+
+        #
+        # Formats the ancestry options of the field. Returns a hash with ancestors & root.
+        #
+        def format_root_ancestry_options(root_name)
+          root_proc = format_root_name(root_name)
+          ancestors = [root_proc]
+
+          { root: root_proc, ancestors: ancestors }.with_indifferent_access.reject { |_, v| v.blank? }
+        end
+
+
+        #
+        # Formats the ancestry options of the field. Returns a hash with ancestors & root.
+        #
+        def format_field_ancestry_options(field_name_proc, options = {})
+          ancestors = options[:ancestors].try(:dup) || []
+          ancestors << field_name_proc
+
+          { ancestors: ancestors }.with_indifferent_access.reject { |_, v| v.blank? }
+        end
+
+
+        #
+        # Formats the configuration of the field and returns the default configuration if not specified.
+        #
+        def format_field_configuration(type = nil, options = {}, &block)
+          options = type if type.is_a?(Hash) && options.empty?
+
+          options[:type] = sanitize_param_data_type(type, &block)
+          options[:item_type] = options[:item_type].to_s if options.has_key?(:item_type)
+
+          DEFAULT_PARAM_OPTIONS.merge(options).with_indifferent_access
+        end
+
+        DEFAULT_PARAM_OPTIONS = { nodoc: false, required: false }
+        private_constant :DEFAULT_PARAM_OPTIONS
+
+
+        #
+        # Returns the type of the param and adds a deprecation warning if not specified.
+        #
+        def sanitize_param_data_type(type, &block)
+          if type.is_a?(Hash) || type.blank?
+            deprecated_type_warning
+            type = block_given? ? DEFAULT_BLOCK_DATA_TYPE : DEFAULT_DATA_TYPE
+          end
+
+          type.to_s
+        end
+
+        DEFAULT_DATA_TYPE = 'string'
+        private_constant :DEFAULT_DATA_TYPE
+
+        DEFAULT_BLOCK_DATA_TYPE = 'hash'
+        private_constant :DEFAULT_BLOCK_DATA_TYPE
+
+
+        #
+        # Adds deprecation warning if the type argument is not specified when defining a valid param.
+        #
+        def deprecated_type_warning
+          ActiveSupport::Deprecation.warn(
+            'Please specify the `type` of the parameter as the second argument. If not specified, '\
+              'it will default to `:string`. This default behavior will be deprecated in the next major '\
+              'version and will need to be explicitly specified. e.g. `post.valid :message, :text, required: true`',
+            caller
+          )
         end
       end
 
 
+      def valid_params_tree(requested_context = action_name.to_sym)
+        contextual_key(requested_context, :valid_params)
+          .to_h
+          .inject(ActiveSupport::HashWithIndifferentAccess.new) do |hsh, (field_name_proc, field_config)|
+
+          field_name = field_name_proc.call(self.class)
+          if field_config.has_key?(:ancestors)
+            ancestors = field_config[:ancestors].map { |ancestor_key| ancestor_key.call(self.class) }
+            parent = ancestors.inject(hsh) do |traversed_hash, ancestor_name|
+              traversed_hash[ancestor_name] ||= {}
+              traversed_hash[ancestor_name]
+            end
+
+            parent[field_name] = { :_config => field_config.except(:root, :ancestors) }
+          else
+            hsh[field_name] = { :_config => field_config }
+          end
+
+          hsh
+        end
+      end
+
       #
       # Lists all valid parameters for the current action. Falls back to the
       # valid parameters for the default context.
@@ -246,12 +376,7 @@ module Brainstem
       # descriptions or sub-hashes.
       #
       def brainstem_valid_params(requested_context = action_name.to_sym, root_param_name = brainstem_model_name)
-        contextual_key(requested_context, :valid_params)
-          .to_h
-          .select do |k, v|
-            root = v[:root].respond_to?(:call) ? v[:root].call(self.class) : v[:root]
-            root.to_s == root_param_name.to_s
-          end
+        valid_params_tree(requested_context)[root_param_name.to_s]
       end
       alias_method :brainstem_valid_params_for, :brainstem_valid_params
 
@@ -293,7 +418,6 @@ module Brainstem
           configuration[DEFAULT_BRAINSTEM_PARAMS_CONTEXT][key.to_sym]
         end
       end
-
       private :contextual_key
     end
   end