brainstem 1.4.1 → 2.0.0

data/lib/brainstem/api_docs/sinks/stdout_sink.rb

@@ -12,23 +12,19 @@ module Brainstem
           puts_method.call(output)
         end
 
-
         ########################################################################
         private
         ########################################################################
 
-
         def valid_options
           super | [ :puts_method ]
         end
 
-
         #
         # Storage for holding the writing method.
         #
         attr_writer :puts_method
 
-
         #
         # Callable method for writing data to a buffer (by default stdout).
         #
@@ -37,7 +33,6 @@ module Brainstem
         def puts_method
           @puts_method ||= $stdout.method(:puts)
         end
-
       end
     end
   end

data/lib/brainstem/cli.rb

@@ -2,7 +2,6 @@
 Dir.glob(File.expand_path('../cli/**/*.rb', __FILE__)).each { |f| require f }
 require 'brainstem/concerns/optional'
 
-
 #
 # General manager for CLI requests. Takes incoming user input and routes to a
 # subcommand.
@@ -21,7 +20,6 @@ module Brainstem
       new(args, options).call
     end
 
-
     #
     # Creates a new instance of the Cli to respond to user input.
     #
@@ -35,7 +33,6 @@ module Brainstem
       self.requested_command  = args.shift
     end
 
-
     #
     # Routes to an application endpoint depending on given options.
     #
@@ -51,24 +48,20 @@ module Brainstem
       self
     end
 
-
     #
     # Holds a copy of the initial given args for debugging purposes.
     #
     attr_accessor :_args
 
-
     #
     # Storage for the extracted command.
     #
     attr_accessor :requested_command
 
-
     ################################################################################
     private
     ################################################################################
 
-
     #
     # A whitelist of valid options that can be applied to the instance.
     #
@@ -80,7 +73,6 @@ module Brainstem
       ]
     end
 
-
     #
     # A basic routing table where the keys are the command to invoke, and where
     # the value is a callable object or class that will be called with the
@@ -92,7 +84,6 @@ module Brainstem
       { 'generate' => Brainstem::CLI::GenerateApiDocsCommand }
     end
 
-
     #
     # Retrieves the help text and subs any placeholder values.
     #
@@ -101,13 +92,11 @@ module Brainstem
         .gsub('EXECUTABLE_NAME', EXECUTABLE_NAME)
     end
 
-
     #
     # Stores the method we should call to run the user command.
     #
     attr_writer :command_method
 
-
     #
     # Reader for the method to invoke. By default, will output the help text
     # when called.
@@ -122,13 +111,11 @@ module Brainstem
       end
     end
 
-
     #
     # Stores the method we should use to log messages.
     #
     attr_writer :log_method
 
-
     #
     # Reader for the method to log. By default, will print to stdout when
     # called.

data/lib/brainstem/cli/abstract_command.rb

@@ -25,7 +25,6 @@ module Brainstem
         instance
       end
 
-
       #
       # Returns a new instance of the command with options set.
       #
@@ -35,7 +34,6 @@ module Brainstem
         extract_options!
       end
 
-
       #
       # Returns the hash of default options used as a base into which cli args
       # are merged.
@@ -44,7 +42,6 @@ module Brainstem
         {}
       end
 
-
       #
       # Kicks off execution of app-level code. Has available to it +options+,
       # which contains the options extracted from the command line.
@@ -54,19 +51,16 @@ module Brainstem
           "Override #call and implement your application logic."
       end
 
-
       #
       # Storage for given options.
       #
       attr_accessor :options
 
-
       #
       # Storage for passed, unparsed args.
       #
       attr_accessor :args
 
-
       #
       # Extracts command-line options for this specific command based on the
       # +OptionParser+ specified in +self.option_parser+.
@@ -77,7 +71,6 @@ module Brainstem
         option_parser.order!(args)
       end
 
-
       #
       # An +OptionParser+ instance that specifies how options should be
       # extracted specific to this command.

data/lib/brainstem/cli/generate_api_docs_command.rb

@@ -24,19 +24,16 @@ module Brainstem
   module CLI
     class GenerateApiDocsCommand < AbstractCommand
 
-
       def call
         ensure_sink_specified!
         construct_builder!
         present_atlas!
       end
 
-
       def default_sink_method
         Brainstem::ApiDocs::Sinks::ControllerPresenterMultifileSink.method(:new)
       end
 
-
       def default_options
         {
           sink: {
@@ -55,10 +52,8 @@ module Brainstem
         }
       end
 
-
       attr_accessor :builder
 
-
       #########################################################################
       private
       #########################################################################
@@ -70,7 +65,6 @@ module Brainstem
         @builder = Brainstem::ApiDocs::Builder.new(builder_options)
       end
 
-
       #
       # Hands the atlas over to the sink.
       #
@@ -78,7 +72,6 @@ module Brainstem
         sink_method.call(sink_options) << builder.atlas
       end
 
-
       #
       # Raises an error unless the user specified a destination for the output.
       #
@@ -86,7 +79,6 @@ module Brainstem
         raise Brainstem::ApiDocs::NoSinkSpecifiedException unless sink_method
       end
 
-
       #
       # Utility method for retrieving the sink.
       #
@@ -94,7 +86,6 @@ module Brainstem
         @sink_method ||= options[:sink][:method]
       end
 
-
       #
       # Utility method for retrieving builder options.
       #
@@ -102,7 +93,6 @@ module Brainstem
         @builder_options ||= options[:builder]
       end
 
-
       #
       # Utility method for retrieving sink options.
       #
@@ -110,7 +100,6 @@ module Brainstem
         @sink_options ||= options[:sink][:options]
       end
 
-
       #
       # Defines the option parser for this command.
       #
@@ -121,39 +110,27 @@ module Brainstem
         OptionParser.new do |opts|
           opts.banner = "Usage: generate [options]"
 
-          opts.on('-m', '--multifile-presenters-and-controllers',
-                  'dumps presenters and controllers to separate files (default)') do |o|
-            options[:sink][:method] = \
-              Brainstem::ApiDocs::Sinks::ControllerPresenterMultifileSink.method(:new)
-          end
-
-
           opts.on('--host-env-file=PATH', "path to host app's entry file") do |o|
             options[:builder][:args_for_introspector][:rails_environment_file] = o
           end
 
-
           opts.on('-o RELATIVE_DIR', '--output-dir=RELATIVE_DIR',
                   'specifies directory which to output if relevant') do |o|
             options[:sink][:options][:write_path] = o
           end
 
-
           opts.on('--base-presenter-class=CLASS', "which class to look up presenters on") do |o|
             options[:builder][:args_for_introspector][:base_presenter_class] = o
           end
 
-
           opts.on('--base-controller-class=CLASS', "which class to look up controllers on") do |o|
             options[:builder][:args_for_introspector][:base_controller_class] = o
           end
 
-
           opts.on('--base-application-class=CLASS', "which class to look up routes on") do |o|
             options[:builder][:args_for_introspector][:base_application_class] = o
           end
 
-
           opts.on('--controller-matches=MATCH',
                   'a case-sensitive regexp used to winnow the list of '\
                   'controllers. It is matched against the constant, not '\
@@ -164,10 +141,57 @@ module Brainstem
             options[:builder][:args_for_atlas][:controller_matches].push(matcher)
           end
 
-
           opts.on('--markdown', 'use markdown format') do |o|
             options[:sink][:options][:format] = :markdown
           end
+
+          opts.on('-m', '--multifile-presenters-and-controllers',
+            'dumps presenters and controllers to separate files (default)') do |o|
+            if options[:sink][:options][:format] == :oas_v2
+              raise NotImplementedError.new("Multi File support for Open API Specification is not supported yet")
+            else
+              options[:sink][:method] = Brainstem::ApiDocs::Sinks::ControllerPresenterMultifileSink.method(:new)
+            end
+          end
+
+          opts.on('--output-extension=EXTENSION', 'extension that should be used for output files') do |extension|
+            options[:sink][:options][:output_extension] = extension
+          end
+
+          #########################################################
+          #                                                       #
+          # Open API Specification generation specific commands:  #
+          #                                                       #
+          #########################################################
+
+          # Future proofing for different Open API Specification versions.
+          opts.on('--open-api-specification=VERSION',
+                  'dumps an Open API Specification for presenters and controllers in a single file') do |oas_version|
+            case oas_version.to_i
+              when 2
+                options[:sink][:options][:format] = :oas_v2
+              else
+                raise NotImplementedError.new(
+                  "Please specify the version of Open API Specification to be generated e.g. --open-api-specification=2"
+                )
+            end
+            options[:sink][:method] = Brainstem::ApiDocs::Sinks::OpenApiSpecificationSink.method(:new)
+          end
+
+          opts.on('--api-version=API_VERSION',
+                  'sets the version of the generated documentation') do |api_version|
+            options[:sink][:options][:api_version] = api_version
+          end
+
+          opts.on('--ignore-tagging',
+                  'does not add the tag definitions in the Open API Specification') do |api_version|
+            options[:sink][:options][:ignore_tagging] = true
+          end
+
+          opts.on('--oas-filename-pattern=PATTERN',
+                  'defines the naming pattern of the Open API Specification file') do |pattern|
+            options[:sink][:options][:oas_filename_pattern] = pattern
+          end
         end
       end
     end

data/lib/brainstem/concerns/controller_dsl.rb

@@ -13,7 +13,6 @@ module Brainstem
         reset_configuration!
       end
 
-
       module ClassMethods
         def reset_configuration!
           configuration.nest! :_default
@@ -22,10 +21,11 @@ module Brainstem
             default.nest! :transforms
             default.nonheritable! :title
             default.nonheritable! :description
+            default.nonheritable! :tag
+            default.nonheritable! :tag_groups
           end
         end
 
-
         #
         # In order to correctly scope the DSL, we must have a context under
         # which keys are stored. The default context is _default (to avoid
@@ -42,7 +42,6 @@ module Brainstem
         #
         attr_accessor :brainstem_params_context
 
-
         #
         # Container method that sets up base scoping for the configuration.
         #
@@ -52,7 +51,6 @@ module Brainstem
           self.brainstem_params_context = nil
         end
 
-
         #
         # Temporary implementation to track controllers that have been documented.
         #
@@ -60,7 +58,6 @@ module Brainstem
           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,
@@ -71,40 +68,91 @@ module Brainstem
           configuration[brainstem_params_context][:nodoc] = true
         end
 
+        #
+        # Specifies which presenter is used for the controller / action.
+        # By default, expects presentation on all methods, and falls back to the
+        # class derived from +brainstem_model_name+ if a name is not
+        # given.
+        #
+        # Setting the +:nodoc+ option marks this presenter as 'internal use only',
+        # and causes formatters to display this as not indicated.
+        #
+        # @param [Class] target_class the target class of the presenter (i.e the model it presents)
+        # @param [Hash] options options to record with the presenter
+        # @option options [Boolean] :nodoc whether this presenter should not be output in the documentation.
+        #
+        def presents(target_class = :default, options = { nodoc: false })
+          raise "`presents` must be a class (in #{self.to_s})" \
+            unless target_class.is_a?(Class) || target_class == :default || target_class.nil?
+
+          target_class = brainstem_model_class if target_class == :default
+          configuration[brainstem_params_context][:presents] = options.merge(target_class: target_class)
+        end
 
         #
-        # Changes context to a specific action context. Allows specification
-        # of per-action configuration.
+        # Specifies a title to be used in the description of a class. Can also
+        # be used for method section titles.
         #
-        # Instead of using this method, it's advised simply to use +actions+
-        # with a single method name. While marked as private, since it is
-        # usually used within a +class_eval+ block thanks to
-        # +brainstem_params+, this has little effect.
+        # Setting the +:nodoc+ option marks this title as 'internal use only',
+        # and causes formatters to fall back to the controller constant or to
+        # the action name as appropriate. If you are trying to set the entire
+        # controller or action as nondocumentable, instead, use the
+        # +.nodoc!+ method in the desired context without a block.
         #
-        # Originally, this method was named +action+ for parity with the plural
-        # version. However, this conflicts in multiple ways with Rails, so it
-        # has been renamed.
+        # @param [String] text The title to set
+        # @param [Hash] options options to record with the title
+        # @option options [Boolean] :nodoc whether this title should not be output in the documentation.
         #
-        # @private
+        def title(text, options = { nodoc: false })
+          configuration[brainstem_params_context][:title] = options.merge(info: text)
+        end
+
         #
-        # @param [Symbol] name the name of the context
-        # @param [Proc] block the proc to be evaluated in the context
+        # Specifies a low-level description of a particular context, usually
+        # (but not exclusively) reserved for methods.
         #
-        def action_context(name, &block)
-          new_context = name.to_sym
-          old_context = self.brainstem_params_context
-          self.brainstem_params_context = new_context
+        # Setting the +:nodoc+ option marks this description as 'internal use
+        # only', and causes formatters not to display a description.
+        #
+        # @param [String] text The description to set
+        # @param [Hash] options options to record with the description
+        # @option options [Boolean] :nodoc whether this description should not be output in the documentation.
+        #
+        def description(text, options = { nodoc: false })
+          configuration[brainstem_params_context][:description] = options.merge(info: text)
+        end
 
-          self.configuration[new_context] ||= Brainstem::DSL::Configuration.new(
-            self.configuration[DEFAULT_BRAINSTEM_PARAMS_CONTEXT]
-          )
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # Specifies the tag name to be used in tagging a class.
+        #
+        # @param [String] tag_name The name of the tag.
+        #
+        def tag(tag_name)
+          unless brainstem_params_context == DEFAULT_BRAINSTEM_PARAMS_CONTEXT
+            raise "`tag` is not endpoint specific and is defined on the controller"
+          end
 
-          class_eval(&block)
-          self.brainstem_params_context = old_context
+          configuration[brainstem_params_context][:tag] = tag_name
         end
 
-        private :action_context
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # Specifies an array of tag names to group the class under. Used for the x-tags OAS vendor extension.
+        #
+        # @param [Array<String>] tag_group_names Array of tag group names
+        #
+        def tag_groups(*tag_group_names)
+          unless brainstem_params_context == DEFAULT_BRAINSTEM_PARAMS_CONTEXT
+            raise "`tag_groups` is not endpoint specific and is defined on the controller"
+          end
 
+          configuration[brainstem_params_context][:tag_groups] = tag_group_names.flatten
+        end
 
         #
         # Invokes +action+ for each symbol in the argument list. Used to
@@ -114,7 +162,6 @@ module Brainstem
           axns.flatten.each { |name| action_context name, &block }
         end
 
-
         #
         # Allows the bulk specification of +:root+ options. Useful for
         # denoting parameters which are nested under a resource.
@@ -138,45 +185,193 @@ module Brainstem
           with_options(format_root_ancestry_options(root), &block)
         end
 
-
         #
         # Adds a param to the list of valid params, storing
         # 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 [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,
+        # @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.
+        # @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, type = nil, options = {}, &block)
+        def valid(name, type = nil, options = {}, &block)
           valid_params = configuration[brainstem_params_context][:valid_params]
-          field_config = format_field_configuration(type, options, &block)
+          param_config = format_field_configuration(valid_params, 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]
+          formatted_name = convert_to_proc(name)
+          valid_params[formatted_name] = param_config
 
-          # 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
+          with_options(format_ancestry_options(formatted_name, param_config), &block) if block_given?
+        end
+
+        #
+        # Allows defining a custom response structure for an action.
+        #
+        # @param [Symbol] type the data type of the response.
+        # @param [Hash] options
+        # @option options [String] :info the documentation for the param
+        # @option options [Boolean] :nodoc should this block appear in the documentation?
+        # @option options [String, Symbol] :item_type The data type of the items contained in a field.
+        #   Ideally used when the data type of the response is an `array`.
+        #
+        def response(type, options = {}, &block)
+          configuration[brainstem_params_context].nest! :custom_response
+          custom_response = configuration[brainstem_params_context][:custom_response]
+
+          custom_response[:_config] = format_field_configuration(
+            custom_response,
+            type,
+            options,
+            &block
+          )
+          class_eval(&block) if block_given?
+        end
+
+        #
+        # Allows defining a field block for a custom response
+        #
+        # @param [Symbol] name the name of the field block of the response.
+        # @param [Symbol] type the data type of the response.
+        # @param [Hash] options
+        # @option options [String] :info the documentation for the param
+        # @option options [String, Symbol] :item_type The data type of the items contained in a field.
+        #   Ideally used when the data type of the response is an `array`.
+        #
+        def fields(name, type, options = {}, &block)
+          custom_response = configuration[brainstem_params_context][:custom_response]
+          raise "`fields` must be nested under a response block" if custom_response.nil?
+
+          formatted_name = convert_to_proc(name)
+          field_block_config = format_field_configuration(custom_response, type, options, &block)
+
+          custom_response[formatted_name] = field_block_config
+          with_options(format_ancestry_options(formatted_name, field_block_config), &block)
+        end
+
+        #
+        # Allows defining a field either under a field block or the custom response block.
+        #
+        # @param [Symbol] name the name of the field of the response.
+        # @param [Symbol] type the data type of the response.
+        # @param [Hash] options
+        # @option options [String] :info the documentation for the param
+        # @option options [String, Symbol] :item_type The data type of the items contained in a field.
+        #   Ideally used when the data type of the response is an `array`.
+        #
+        def field(name, type, options = {})
+          custom_response = configuration[brainstem_params_context][:custom_response]
+          raise "`fields` must be nested under a response block" if custom_response.nil?
+
+          formatted_name = convert_to_proc(name)
+          custom_response[formatted_name] = format_field_configuration(custom_response, type, options)
+        end
+
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # Unique string used to identify the operation. The id MUST be unique among all operations
+        # described in the API. Tools and libraries MAY use the operation_id to uniquely identify an
+        # operation, therefore, it is recommended to follow common programming naming conventions.
+        #
+        # @param [String] unique_id
+        #
+        def operation_id(unique_id)
+          if brainstem_params_context == DEFAULT_BRAINSTEM_PARAMS_CONTEXT
+            raise "`operation_id` is endpoint specific and cannot be defined on the controller"
           end
 
-          procified_field_name = format_field_name(field_name)
-          valid_params[procified_field_name] = field_config
+          configuration[brainstem_params_context][:operation_id] = unique_id
+        end
+
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # A list of MIME types the endpoints can consume. This overrides the default consumes definition
+        # on the Info object in the Open API Specification.
+        #
+        # @param [Array<String>] mime_types Array of mime types
+        #
+        def consumes(*mime_types)
+          configuration[brainstem_params_context][:consumes] = mime_types.flatten
+        end
+
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # A list of MIME types the endpoints can produce. This overrides the default produces definition
+        # on the Info object in the Open API Specification.
+        #
+        # @param [Array<String>] mime_types Array of mime types
+        #
+        def produces(*mime_types)
+          configuration[brainstem_params_context][:produces] = mime_types.flatten
+        end
 
-          with_options(format_field_ancestry_options(procified_field_name, field_config), &block) if block_given?
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # A declaration of which security schemes are applied for this operation. The list of values
+        # describes alternative security schemes that can be used. This definition overrides any declared
+        # top-level security. To remove a top-level security declaration, an empty array can be used.
+        #
+        # @param [Array<Hash>] schemes Array of security schemes applicable to the endpoint
+        #
+        def security(*schemes)
+          configuration[brainstem_params_context][:security] = schemes.flatten
         end
 
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # Additional external documentation for this operation.
+        # e.g {
+        #       "description": "Find more info here",
+        #       "url": "https://swagger.io"
+        #     }
+        #
+        # @param [Hash] doc_config Hash with the `description` & `url` properties of the external documentation.
+        #
+        def external_doc(doc_config)
+          configuration[brainstem_params_context][:external_doc] = doc_config
+        end
+
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # The transfer protocol for the operation. Values MUST be from the list: "http", "https", "ws", "wss".
+        # The value overrides the default schemes definition in the Info Object.
+        #
+        # @param [Hash] schemes Array of schemes applicable to the endpoint
+        #
+        def schemes(*schemes)
+          configuration[brainstem_params_context][:schemes] = schemes.flatten
+        end
+
+        ####################################################
+        # Used only for Open API Specification generation. #
+        ####################################################
+        #
+        # Declares this operation to be deprecated. Usage of the declared operation should be refrained.
+        #
+        # @param [Hash] schemes Array of schemes applicable to the endpoint
+        #
+        def deprecated(deprecated)
+          configuration[brainstem_params_context][:deprecated] = deprecated
+        end
 
         #
         # Adds a transform to the list of transforms. Used to rename incoming
@@ -198,68 +393,37 @@ module Brainstem
         end
         alias_method :transforms, :transform
 
-
-        #
-        # Specifies which presenter is used for the controller / action.
-        # By default, expects presentation on all methods, and falls back to the
-        # class derived from +brainstem_model_name+ if a name is not
-        # given.
-        #
-        # Setting the +:nodoc+ option marks this presenter as 'internal use only',
-        # and causes formatters to display this as not indicated.
-        #
-        # @param [Class] target_class the target class of the presenter (i.e
-        #   the model it presents)
-        # @param [Hash] options options to record with the presenter
-        # @option [Boolean] options :nodoc whether this presenter should not
-        #   be output in the documentation.
         #
+        # Changes context to a specific action context. Allows specification
+        # of per-action configuration.
         #
-        def presents(target_class = :default, options = { nodoc: false })
-          raise "`presents` must be a class (in #{self.to_s})" \
-            unless target_class.is_a?(Class) || target_class == :default || target_class.nil?
-
-          target_class = brainstem_model_class if target_class == :default
-          configuration[brainstem_params_context][:presents] = \
-            options.merge(target_class: target_class)
-        end
-
-
+        # Instead of using this method, it's advised simply to use +actions+
+        # with a single method name. While marked as private, since it is
+        # usually used within a +class_eval+ block thanks to
+        # +brainstem_params+, this has little effect.
         #
-        # Specifies a low-level description of a particular context, usually
-        # (but not exclusively) reserved for methods.
+        # Originally, this method was named +action+ for parity with the plural
+        # version. However, this conflicts in multiple ways with Rails, so it
+        # has been renamed.
         #
-        # Setting the +:nodoc+ option marks this description as 'internal use
-        # only', and causes formatters not to display a description.
+        # @private
         #
-        # @param [String] text The description to set
-        # @param [Hash] options options to record with the description
-        # @option [Boolean] options :nodoc whether this description should not
-        #   be output in the documentation.
+        # @param [Symbol] name the name of the context
+        # @param [Proc] block the proc to be evaluated in the context
         #
-        def description(text, options = { nodoc: false })
-          configuration[brainstem_params_context][:description] = options.merge(info: text)
-        end
+        def action_context(name, &block)
+          new_context = name.to_sym
+          old_context = self.brainstem_params_context
+          self.brainstem_params_context = new_context
 
+          self.configuration[new_context] ||= Brainstem::DSL::Configuration.new(
+            self.configuration[DEFAULT_BRAINSTEM_PARAMS_CONTEXT]
+          )
 
-        #
-        # Specifies a title to be used in the description of a class. Can also
-        # be used for method section titles.
-        #
-        # Setting the +:nodoc+ option marks this title as 'internal use only',
-        # and causes formatters to fall back to the controller constant or to
-        # the action name as appropriate. If you are trying to set the entire
-        # controller or action as nondocumentable, instead, use the discrete
-        # +.nodoc!+ method in the desired context without a block.
-        #
-        # @param [String] text The title to set
-        # @param [Hash] options options to record with the title
-        # @option [Boolean] options :nodoc whether this title should not be
-        #   output in the documentation.
-        #
-        def title(text, options = { nodoc: false })
-          configuration[brainstem_params_context][:title] = options.merge(info: text)
+          class_eval(&block)
+          self.brainstem_params_context = old_context
         end
+        private :action_context
 
         #
         # Converts the field name into a Proc.
@@ -267,11 +431,10 @@ module Brainstem
         # @param [String, Symbol, Proc] text The title to set
         # @return [Proc]
         #
-        def format_field_name(field_name_or_proc)
+        def convert_to_proc(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
-
+        alias_method :format_root_name, :convert_to_proc
 
         #
         # Formats the ancestry options of the field. Returns a hash with ancestors & root.
@@ -283,67 +446,49 @@ module Brainstem
           { 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.
+        # Formats the ancestry options of the field. Returns a hash with ancestors.
         #
-        def format_field_ancestry_options(field_name_proc, options = {})
+        def format_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.
+        # Formats the configuration of the param 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?
+        def format_field_configuration(configuration_map, type, options = {}, &block)
+          field_config = options.with_indifferent_access
 
-          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
+          field_config[:type] = type.to_s
+          if options.has_key?(:item_type)
+            field_config[:item_type] = field_config[:item_type].to_s
+          elsif field_config[:type] == 'array'
+            field_config[:item_type] = block_given? ? 'hash' : 'string'
+          end
 
+          # Inherit `nodoc` attribute from parent
+          parent_key = (field_config[:ancestors] || []).reverse.first
+          if parent_key && (parent_field_config = configuration_map[parent_key])
+            field_config[:nodoc] ||= !!parent_field_config[:nodoc]
+          end
 
-        #
-        # 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
+          # Rollup `required` attribute to ancestors if true
+          if field_config[:required]
+            (field_config[:ancestors] || []).reverse.each do |ancestor_key|
+              configuration_map[ancestor_key][:required] = true if configuration_map.has_key?(ancestor_key)
+            end
           end
 
-          type.to_s
+          DEFAULT_FIELD_CONFIG.merge(field_config).with_indifferent_access
         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
+        DEFAULT_FIELD_CONFIG = { nodoc: false, required: false }
+        private_constant :DEFAULT_FIELD_CONFIG
       end
 
-
       def valid_params_tree(requested_context = action_name.to_sym)
         contextual_key(requested_context, :valid_params)
           .to_h
@@ -380,7 +525,6 @@ module Brainstem
       end
       alias_method :brainstem_valid_params_for, :brainstem_valid_params
 
-
       #
       # Lists all incoming param keys that will be rewritten to use a different
       # name for internal usage for the current action.
@@ -401,7 +545,6 @@ module Brainstem
       end
       alias_method :transforms_for, :transforms
 
-
       #
       # Retrieves a specific key in a given context, or if that doesn't exist,
       # falls back to the parent context.