brainstem 2.0.0 → 2.1.0

data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/tags_formatter.rb

@@ -109,7 +109,7 @@ module Brainstem
             def format_tag_data(controller)
               {
                 name:        tag_name(controller),
-                description: format_description(controller.description),
+                description: format_sentence(controller.description),
               }.reject { |_, v| v.blank? }
             end
           end

data/lib/brainstem/api_docs/presenter.rb

@@ -21,14 +21,16 @@ module Brainstem
           :filename_pattern,
           :filename_link_pattern,
           :document_empty_associations,
-          :document_empty_filters
+          :document_empty_filters,
+          :include_internal
         ]
       end
 
       attr_accessor :const,
                     :target_class,
                     :document_empty_associations,
-                    :document_empty_filters
+                    :document_empty_filters,
+                    :include_internal
 
       attr_writer   :filename_pattern,
                     :filename_link_pattern
@@ -75,7 +77,7 @@ module Brainstem
       delegate :find_by_class => :atlas
 
       def nodoc?
-        configuration[:nodoc]
+        nodoc_for?(configuration)
       end
 
       def title
@@ -98,7 +100,7 @@ module Brainstem
       alias_method :valid_fields_in, :valid_fields
 
       def invalid_field?(field)
-        field.options[:nodoc]
+        nodoc_for?(field.options)
       end
 
       def nested_field?(field)
@@ -131,7 +133,7 @@ module Brainstem
       end
 
       def documentable_filter?(_, filter)
-        !filter[:nodoc] &&
+        !nodoc_for?(filter) &&
           (
             document_empty_filters? || # document empty filters or
             !(filter[:info] || "").empty? # has info string
@@ -143,7 +145,7 @@ module Brainstem
       end
 
       def valid_sort_orders
-        configuration[:sort_orders].to_h.reject {|k, v| v[:nodoc] }
+        configuration[:sort_orders].to_h.reject {|_k, v| nodoc_for?(v) }
       end
 
       def valid_associations
@@ -168,7 +170,7 @@ module Brainstem
       # @return [Bool] document this association?
       #
       def documentable_association?(_, association)
-        !association.options[:nodoc] && # not marked nodoc and
+        !nodoc_for?(association.options) && # not marked nodoc and
           (
             document_empty_associations? || # document empty associations or
             !(association.description.nil? || association.description.empty?) # has description
@@ -196,7 +198,7 @@ module Brainstem
       #
       def contextual_documentation(key)
         configuration.has_key?(key) &&
-          !configuration[key][:nodoc] &&
+          !nodoc_for?(configuration[key]) &&
           configuration[key][:info]
       end
 
@@ -210,6 +212,12 @@ module Brainstem
 
         presenter_path.relative_path_from(my_path).to_s
       end
+
+      private
+
+      def nodoc_for?(config)
+        !!(config[:nodoc] || (config[:internal] && !include_internal))
+      end
     end
   end
 end

data/lib/brainstem/api_docs/presenter_collection.rb

@@ -9,10 +9,11 @@ module Brainstem
       include Concerns::Formattable
 
       def valid_options
-        super | [ :presenter_constant_lookup_method ]
+        super | [ :presenter_constant_lookup_method, :include_internal ]
       end
 
       attr_writer :presenter_constant_lookup_method
+      attr_accessor :include_internal
 
       #
       # Finds or creates a presenter with the given target class and appends it to the
@@ -38,8 +39,9 @@ module Brainstem
       #
       def create_from_target_class(target_class)
         ::Brainstem::ApiDocs::Presenter.new(atlas,
-          target_class: target_class,
-          const:        target_class_to_const(target_class)
+          target_class:     target_class,
+          const:            target_class_to_const(target_class),
+          include_internal: include_internal
         ).tap { |p| self.<< p }
       rescue KeyError
         nil
@@ -54,8 +56,9 @@ module Brainstem
 
       def create_from_presenter_collection(target_class, const)
         ::Brainstem::ApiDocs::Presenter.new(atlas,
-          target_class: target_class,
-          const:        const
+          target_class:     target_class,
+          const:            const,
+          include_internal: include_internal
         ).tap { |p| self.<< p }
       end
 

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

@@ -20,6 +20,7 @@ module Brainstem
             :write_path,
             :oas_filename_pattern,
             :output_extension,
+            :include_internal
           ]
         end
 
@@ -32,7 +33,8 @@ module Brainstem
                       :ignore_tagging,
                       :oas_filename_pattern,
                       :output_extension,
-                      :output
+                      :output,
+                      :include_internal
 
         delegate [:controllers, :presenters] => :atlas
 

data/lib/brainstem/cli/generate_api_docs_command.rb

@@ -158,6 +158,10 @@ module Brainstem
             options[:sink][:options][:output_extension] = extension
           end
 
+          opts.on('--include-internal', 'Generate docs for all `internal!` flagged presenters/controllers') do |_|
+            options[:builder][:args_for_atlas][:include_internal] = true
+          end
+
           #########################################################
           #                                                       #
           # Open API Specification generation specific commands:  #

data/lib/brainstem/concerns/controller_dsl.rb

@@ -8,6 +8,7 @@ module Brainstem
       include Brainstem::Concerns::InheritableConfiguration
 
       DEFAULT_BRAINSTEM_PARAMS_CONTEXT = :_default
+      DYNAMIC_KEY = :_dynamic_key
 
       included do
         reset_configuration!
@@ -64,8 +65,18 @@ module Brainstem
         # whereas setting it within an action context will force that action to
         # be undocumented.
         #
-        def nodoc!
-          configuration[brainstem_params_context][:nodoc] = true
+        def nodoc!(description = true)
+          configuration[brainstem_params_context][:nodoc] = description
+        end
+
+        #
+        # Specifies that the scope should not be documented unless the `--include-internal`
+        # flag is passed in the CLI. Setting this on the default context
+        # will force the controller to be undocumented, whereas setting it
+        # within an action context will force that action to be undocumented.
+        #
+        def internal!(description = true)
+          configuration[brainstem_params_context][:internal] = description
         end
 
         #
@@ -77,11 +88,15 @@ module Brainstem
         # Setting the +:nodoc+ option marks this presenter as 'internal use only',
         # and causes formatters to display this as not indicated.
         #
+        # Setting the +:internal+ option marks this presenter as 'internal use only',
+        # and causes formatters to not display this unless documentation is generated with
+        # `--include-internal` flag.
+        #
         # @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 })
+        def presents(target_class = :default, options = { nodoc: false, internal: false })
           raise "`presents` must be a class (in #{self.to_s})" \
             unless target_class.is_a?(Class) || target_class == :default || target_class.nil?
 
@@ -99,11 +114,18 @@ module Brainstem
         # controller or action as nondocumentable, instead, use the
         # +.nodoc!+ method in the desired context without a block.
         #
+        # Setting the +:internal+ 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 unless documentation is generated with
+        # `--include-internal` flag. If you are trying to set the entire
+        # controller or action as nondocumentable unless internal, instead,
+        # use the +.internal!+ 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 options [Boolean] :nodoc whether this title should not be output in the documentation.
         #
-        def title(text, options = { nodoc: false })
+        def title(text, options = { nodoc: false, internal: false })
           configuration[brainstem_params_context][:title] = options.merge(info: text)
         end
 
@@ -114,11 +136,15 @@ module Brainstem
         # Setting the +:nodoc+ option marks this description as 'internal use
         # only', and causes formatters not to display a description.
         #
+        # Setting the +:internal+ option marks this description as 'internal use
+        # only', and causes formatters not to display a description unless documentation
+        # is generated with `--include-internal` flag.
+        #
         # @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 })
+        def description(text, options = { nodoc: false, internal: false })
           configuration[brainstem_params_context][:description] = options.merge(info: text)
         end
 
@@ -189,7 +215,7 @@ module Brainstem
         # 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 [Symbol] 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
@@ -200,11 +226,11 @@ module Brainstem
         # @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`.
+        #   Only used when the data type of the field is an `array`.
         #
         def valid(name, type = nil, options = {}, &block)
           valid_params = configuration[brainstem_params_context][:valid_params]
-          param_config = format_field_configuration(valid_params, type, options, &block)
+          param_config = format_field_configuration(valid_params, name, type, options, &block)
 
           formatted_name = convert_to_proc(name)
           valid_params[formatted_name] = param_config
@@ -212,6 +238,26 @@ module Brainstem
           with_options(format_ancestry_options(formatted_name, param_config), &block) if block_given?
         end
 
+        #
+        # Adds a param that has a dynamic key to the list of valid params, storing
+        # the info sent with it.
+        #
+        # @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.
+        #   Only used when the data type of the field is an `array`.
+        #
+        def valid_dynamic_param(type, options = {}, &block)
+          valid(DYNAMIC_KEY, type, options, &block)
+        end
+
         #
         # Allows defining a custom response structure for an action.
         #
@@ -220,7 +266,7 @@ module Brainstem
         # @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`.
+        #   Only used when the data type of the response is an `array`.
         #
         def response(type, options = {}, &block)
           configuration[brainstem_params_context].nest! :custom_response
@@ -228,6 +274,7 @@ module Brainstem
 
           custom_response[:_config] = format_field_configuration(
             custom_response,
+            nil,
             type,
             options,
             &block
@@ -243,19 +290,32 @@ module Brainstem
         # @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`.
+        #   Only 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)
+          field_block_config = format_field_configuration(custom_response, name, 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 block with a dynamic key for a custom 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.
+        #   Only used when the data type of the response is an `array`.
+        #
+        def dynamic_key_fields(type, options = {}, &block)
+          fields(DYNAMIC_KEY, type, options, &block)
+        end
+
         #
         # Allows defining a field either under a field block or the custom response block.
         #
@@ -264,14 +324,27 @@ module Brainstem
         # @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`.
+        #   Only 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)
+          custom_response[formatted_name] = format_field_configuration(custom_response, name, type, options)
+        end
+
+        #
+        # Allows defining a field with a dynamic key either under a field block or the custom response block.
+        #
+        # @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.
+        #   Only used when the data type of the response is an `array`.
+        #
+        def dynamic_key_field(type, options = {})
+          field(DYNAMIC_KEY, type, options)
         end
 
         ####################################################
@@ -459,10 +532,12 @@ module Brainstem
         #
         # Formats the configuration of the param and returns the default configuration if not specified.
         #
-        def format_field_configuration(configuration_map, type, options = {}, &block)
+        def format_field_configuration(configuration_map, name, type, options = {}, &block)
           field_config = options.with_indifferent_access
 
           field_config[:type] = type.to_s
+          field_config[:dynamic_key] = true if name.present? && name.to_sym == DYNAMIC_KEY
+
           if options.has_key?(:item_type)
             field_config[:item_type] = field_config[:item_type].to_s
           elsif field_config[:type] == 'array'
@@ -475,12 +550,7 @@ module Brainstem
             field_config[:nodoc] ||= !!parent_field_config[:nodoc]
           end
 
-          # 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
+          field_config.delete(:nested_levels) if field_config[:nested_levels].to_i < 2
 
           DEFAULT_FIELD_CONFIG.merge(field_config).with_indifferent_access
         end

data/lib/brainstem/concerns/presenter_dsl.rb

@@ -39,16 +39,20 @@ module Brainstem
           AssociationsBlock.new(configuration, &block)
         end
 
-        def title(str, options = { nodoc: false })
+        def title(str, options = { nodoc: false, internal: false })
           configuration[:title] = options.merge(info: str)
         end
 
-        def description(str, options = { nodoc: false })
+        def description(str, options = { nodoc: false, internal: false })
           configuration[:description] = options.merge(info: str)
         end
 
-        def nodoc!
-          configuration[:nodoc] = true
+        def nodoc!(description = true)
+          configuration[:nodoc] = description
+        end
+
+        def internal!(description = true)
+          configuration[:internal] = description
         end
 
         #
@@ -93,6 +97,8 @@ module Brainstem
         #   @option options [String] :info Docstring for the sort order
         #   @option options [Boolean] :nodoc Whether this sort order be
         #     included in the generated documentation
+        #   @option options [Boolean] :direction Whether this sort order
+        #     has direction based ordering (asc/desc). Defaults to true
         #
         # @overload sort_order(name, options, &block)
         #   @yieldparam scope [ActiveRecord::Relation] The scope representing
@@ -107,10 +113,12 @@ module Brainstem
         # @raise [ArgumentError] if neither an order string or block is given.
         #
         def sort_order(name, *args, &block)
-          valid_options = %w(info nodoc)
-          options       = args.extract_options!
-                            .select { |k, v| valid_options.include?(k.to_s) }
-          order         = args.first
+          valid_options       = %w(info nodoc internal direction)
+          options             = args.extract_options!
+                                  .select { |k, v| valid_options.include?(k.to_s) }
+                                  .with_indifferent_access
+          options[:direction] = true unless options.has_key?(:direction)
+          order               = args.first
 
           raise ArgumentError, "A sort order must be given" unless block_given? || order
           configuration[:sort_orders][name] = options.merge({

data/lib/brainstem/dsl/association.rb

@@ -17,6 +17,18 @@ module Brainstem
         options[:info].presence
       end
 
+      def response_key
+        options[:response_key]
+      end
+
+      def polymorphic_classes
+        options[:polymorphic_classes]
+      end
+
+      def type
+        options[:type]
+      end
+
       def method_name
         if options[:dynamic] || options[:lookup]
           nil