brainstem 1.4.1 → 2.0.0

data/lib/brainstem/api_docs/abstract_collection.rb

@@ -19,19 +19,16 @@ module Brainstem
         new(atlas).tap {|n| members.flatten.each { |m| n << m } }
       end
 
-
       def initialize(atlas, options = {})
         self.atlas   = atlas
         self.members = []
         super options
       end
 
-
       attr_accessor :atlas
 
       delegate :find_by_class => :atlas
 
-
       #
       # Handy accessor for extracting the last member of the collection.
       #
@@ -39,7 +36,6 @@ module Brainstem
         members[-1]
       end
 
-
       #
       # Appends a pre-existing object to the collection.
       #
@@ -47,7 +43,6 @@ module Brainstem
         members.push(*objects.flatten)
       end
 
-
       #
       # Iterates over each controller in the collection.
       #
@@ -55,7 +50,6 @@ module Brainstem
         members.each(&block)
       end
 
-
       #
       # Returns a map of each member formatted as specified.
       #
@@ -64,7 +58,6 @@ module Brainstem
           .reject(&:empty?)
       end
 
-
       #
       # Returns a list of each member's filename.
       #
@@ -75,7 +68,6 @@ module Brainstem
         formatted_with_filename(format).map { |arr| arr[1] }
       end
 
-
       #
       # Returns a map of each formatted member and its suggested filename.
       #
@@ -87,25 +79,20 @@ module Brainstem
           .reject { |(buffer, _)| buffer.empty? }
       end
 
-
       def each_formatted_with_filename(format, options = {}, &block)
         formatted_with_filename(format, options)
           .each { |args| block.call(*args) }
       end
 
-
       def each_formatted(format, options = {}, &block)
         formatted(format, options)
           .each { |args| block.call(*args) }
       end
 
-
       def each_filename(format, &block)
         filenames(format).each { |args| block.call(*args) }
       end
 
-
-
       #########################################################################
       protected
       #########################################################################

data/lib/brainstem/api_docs/atlas.rb

@@ -17,7 +17,6 @@ module Brainstem
       extend Forwardable
       include Concerns::Optional
 
-
       def initialize(introspector, options = {})
         self.endpoints          = EndpointCollection.new(self)
         self.controllers        = ControllerCollection.new(self)
@@ -34,21 +33,17 @@ module Brainstem
         validate!
       end
 
-
       attr_accessor :endpoints,
                     :controllers,
                     :presenters,
                     :resolver
 
-
       delegate :find_by_class => :resolver
 
-
       #########################################################################
       private
       #########################################################################
 
-
       #
       # Lists valid options that may be passed on instantiation.
       #
@@ -56,7 +51,6 @@ module Brainstem
         super | [ :controller_matches ]
       end
 
-
       #
       # Ensures the atlas is valid before allowing consumers to make requests
       # of it.
@@ -65,20 +59,17 @@ module Brainstem
         raise InvalidAtlasError, "Atlas is not valid." unless valid?
       end
 
-
       #
       # Set and read the introspector.
       #
       attr_accessor :introspector
 
-
       #
       # Holds +Regexp+s which each controller name must match in order to be
       # included in the list of endpoints.
       #
       attr_accessor :controller_matches
 
-
       #
       # Returns a list of all routes that pass the user's filtering.
       #
@@ -86,7 +77,6 @@ module Brainstem
         introspector.routes.keep_if(&method(:allow_route?))
       end
 
-
       #
       # Constructs +Endpoint+ and +Controller wrappers per route.
       #
@@ -103,7 +93,6 @@ module Brainstem
         end
       end
 
-
       #
       # Extracts declared presents for each endpoint and converts it into a
       # Presenter wrapper object.
@@ -121,7 +110,6 @@ module Brainstem
         end
       end
 
-
       #
       # Returns a list of valid +target_class_to_s => PresenterConst+ pairs,
       # determining validity by whether they descend from the base presenter.
@@ -134,7 +122,6 @@ module Brainstem
         end
       end
 
-
       #
       # Whether this Atlas is valid (i.e. if it has at least one endpoint).
       #
@@ -144,7 +131,6 @@ module Brainstem
         endpoints.count > 0
       end
 
-
       #
       # Returns whether a route's controller passes the limiting regexp passed to the
       # generation command.

data/lib/brainstem/api_docs/builder.rb

@@ -16,7 +16,6 @@ module Brainstem
     class Builder
       include Brainstem::Concerns::Optional
 
-
       def valid_options
         [
           :introspector_method,
@@ -27,7 +26,6 @@ module Brainstem
         ]
       end
 
-
       #
       # @param [Hash] options
       # @option options [Proc] :introspector_method Proc of arity one that
@@ -53,7 +51,6 @@ module Brainstem
         build_atlas!
       end
 
-
       #
       # Builds an introspector.
       #
@@ -61,7 +58,6 @@ module Brainstem
         self.introspector = introspector_method.call(args_for_introspector)
       end
 
-
       #
       # Builds an atlas.
       #
@@ -69,7 +65,6 @@ module Brainstem
         self.atlas = atlas_method.call(introspector, args_for_atlas)
       end
 
-
       #
       # Arguments to be passed to the introspector on creation.
       #
@@ -80,14 +75,12 @@ module Brainstem
         @args_for_introspector ||= {}
       end
 
-
       #
       # Allows passing args to the introspector if - for example - you are
       # using a custom base controller class.
       #
       attr_writer :args_for_introspector
 
-
       #
       # Arguments to be passed to the atlas on creation.
       #
@@ -97,14 +90,12 @@ module Brainstem
         @args_for_atlas ||= {}
       end
 
-
       #
       # Allows passing args to the atlas if - for example - you are
       # specifying match terms for the allowable controller set.
       #
       attr_writer :args_for_atlas
 
-
       #
       # A method which returns the introspector which extracts information
       # about the Brainstem-powered API from the host application.
@@ -122,7 +113,6 @@ module Brainstem
           Introspectors::RailsIntrospector.method(:with_loaded_environment)
       end
 
-
       #
       # Allows setting the introspector_method if - for example - you are using
       # Brainstem on a Sinatra app and you need to customize how lookups for
@@ -130,13 +120,11 @@ module Brainstem
       #
       attr_writer :introspector_method
 
-
       #
       # Holds a reference to the constructed introspector.
       #
       attr_accessor :introspector
 
-
       #
       # A proc of arity 1..2 which takes an introspector and optional options,
       # and which returns a new Atlas.
@@ -149,7 +137,6 @@ module Brainstem
         @atlas_method ||= Atlas.method(:new)
       end
 
-
       #
       # Allows setting the introspector_method if - for example - you are using
       # an alternative formatter and the requisite information is not present
@@ -157,7 +144,6 @@ module Brainstem
       #
       attr_writer :atlas_method
 
-
       #
       # Holds a reference to the constructed atlas.
       #

data/lib/brainstem/api_docs/controller.rb

@@ -11,7 +11,6 @@ module Brainstem
       include Concerns::Optional
       include Concerns::Formattable
 
-
       def initialize(atlas, options = {})
         self.atlas     = atlas
         self.endpoints = EndpointCollection.new(atlas)
@@ -19,18 +18,15 @@ module Brainstem
         yield self if block_given?
       end
 
-
       attr_accessor :const,
                     :name,
                     :endpoints,
                     :filename_pattern,
                     :atlas
 
-
       attr_writer   :filename_pattern,
                     :filename_link_pattern
 
-
       def valid_options
         super | [
           :const,
@@ -41,7 +37,6 @@ module Brainstem
         ]
       end
 
-
       #
       # Adds an existing endpoint to its endpoint collection.
       #
@@ -49,7 +44,6 @@ module Brainstem
         self.endpoints << endpoint
       end
 
-
       def suggested_filename(format)
         filename_pattern
           .gsub('{{namespace}}', const.to_s.deconstantize.underscore)
@@ -57,52 +51,50 @@ module Brainstem
           .gsub('{{extension}}', extension)
       end
 
-
       def suggested_filename_link(format)
         filename_link_pattern
           .gsub('{{name}}', name.to_s)
           .gsub('{{extension}}', extension)
       end
 
-
       def extension
         @extension ||= Brainstem::ApiDocs.output_extension
       end
 
-
       def filename_pattern
         @filename_pattern ||= Brainstem::ApiDocs.controller_filename_pattern
       end
 
-
       def filename_link_pattern
         @filename_link_pattern ||= Brainstem::ApiDocs.controller_filename_link_pattern
       end
 
-
       delegate :configuration => :const
       delegate :find_by_class => :atlas
 
-
       def default_configuration
         configuration[:_default]
       end
 
-
       def nodoc?
         default_configuration[:nodoc]
       end
 
-
       def title
         contextual_documentation(:title) || const.to_s.demodulize
       end
 
-
       def description
         contextual_documentation(:description) || ""
       end
 
+      def tag
+        default_configuration[:tag]
+      end
+
+      def tag_groups
+        default_configuration[:tag_groups]
+      end
 
       #
       # Returns a key if it exists and is documentable.
@@ -113,7 +105,6 @@ module Brainstem
           default_configuration[key][:info]
       end
 
-
       def valid_sorted_endpoints
         endpoints.sorted_with_actions_in_controller(const)
       end

data/lib/brainstem/api_docs/controller_collection.rb

@@ -5,7 +5,6 @@ module Brainstem
   module ApiDocs
     class ControllerCollection < AbstractCollection
 
-
       #
       # Creates a new controller from a route object and appends it to the
       # collection.
@@ -16,7 +15,6 @@ module Brainstem
         ).tap { |controller| self.<< controller }
       end
 
-
       #
       # Finds a controller from a route object.
       #
@@ -26,7 +24,6 @@ module Brainstem
         end
       end
 
-
       #
       # Finds a controller from a route object or creates one if it does not
       # exist.

data/lib/brainstem/api_docs/endpoint.rb

@@ -27,14 +27,12 @@ module Brainstem
         ]
       end
 
-
       def initialize(atlas, options = {})
         self.atlas = atlas
         super options
         yield self if block_given?
       end
 
-
       attr_accessor :path,
                     :http_methods,
                     :controller,
@@ -42,7 +40,6 @@ module Brainstem
                     :action,
                     :atlas
 
-
       #
       # Pretty prints each endpoint.
       #
@@ -50,7 +47,6 @@ module Brainstem
         "#{http_methods.join(" / ")} #{path}"
       end
 
-
       #
       # Merges http methods (for de-duping Rails' routes).
       #
@@ -58,7 +54,6 @@ module Brainstem
         self.http_methods |= methods
       end
 
-
       #
       # Sorts this endpoint in comparison to other endpoints.
       #
@@ -91,7 +86,6 @@ module Brainstem
         end
       end
 
-
       ################################################################################
       # Derived fields
       ################################################################################
@@ -103,21 +97,49 @@ module Brainstem
         action_configuration[:nodoc]
       end
 
-
       def title
         @title ||= contextual_documentation(:title) || action.to_s.humanize
       end
 
-
       def description
         @description ||= contextual_documentation(:description) || ""
       end
 
-
       def valid_params
         @valid_params ||= key_with_default_fallback(:valid_params)
       end
 
+      def custom_response
+        @custom_response ||= action_configuration[:custom_response]
+      end
+
+      def operation_id
+        @operation_id ||= action_configuration[:operation_id]
+      end
+
+      def consumes
+        @consumes ||= key_with_default_fallback(:consumes)
+      end
+
+      def produces
+        @produces ||= key_with_default_fallback(:produces)
+      end
+
+      def security
+        @security ||= key_with_default_fallback(:security)
+      end
+
+      def schemes
+        @schemes ||= key_with_default_fallback(:schemes)
+      end
+
+      def external_docs
+        @external_docs ||= key_with_default_fallback(:external_docs)
+      end
+
+      def deprecated
+        @deprecated ||= key_with_default_fallback(:deprecated)
+      end
 
       #
       # Returns a hash of all params nested under the specified root or
@@ -155,6 +177,48 @@ module Brainstem
         end
       end
 
+      #
+      # Returns a hash of all fields for a custom response nested under the specified
+      # parent fields along with their type, item type & children.
+      #
+      # @return [Hash{Symbol => Hash}] root keys and their type info, item info & children
+      #   nested under them.
+      #
+      def custom_response_configuration_tree
+        return {} unless custom_response.present?
+
+        @custom_response_configuration ||= begin
+          custom_response_fields = custom_response
+            .to_h
+            .deep_dup
+            .with_indifferent_access
+          custom_config_tree = ActiveSupport::HashWithIndifferentAccess.new
+          custom_config_tree[:_config] = custom_response_fields[:_config]
+
+          custom_response_fields
+            .except(:_config)
+            .inject(custom_config_tree) 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
+
+              parent[field_name] = { :_config => field_config.except(:ancestors) }
+            else
+              result[field_name] = { :_config => field_config }
+            end
+
+            result
+          end
+        end
+      end
 
       #
       # Evaluate field name if proc and symbolize it.
@@ -167,7 +231,6 @@ module Brainstem
       end
       alias_method :evaluate_root_name, :evaluate_field_name
 
-
       #
       # Retrieves the +presents+ settings.
       #
@@ -175,7 +238,6 @@ module Brainstem
         key_with_default_fallback(:presents) || {}
       end
 
-
       #
       # Used to retrieve this endpoint's presenter constant.
       #
@@ -185,13 +247,11 @@ module Brainstem
           valid_presents[:target_class]
       end
 
-
       #
       # Stores the +ApiDocs::Presenter+ object associated with this endpoint.
       #
       attr_accessor :presenter
 
-
       ################################################################################
       # Configuration Helpers
       #################################################################################
@@ -202,7 +262,6 @@ module Brainstem
       delegate :configuration => :controller
       delegate :find_by_class => :atlas
 
-
       #
       # Helper for retrieving action-specific configuration from the controller.
       #
@@ -210,7 +269,6 @@ module Brainstem
         configuration[action] || {}
       end
 
-
       #
       # Retrieves default action context from the controller.
       #
@@ -218,7 +276,6 @@ module Brainstem
         configuration[:_default] || {}
       end
 
-
       #
       # Returns a key if it exists and is documentable
       #
@@ -228,17 +285,14 @@ module Brainstem
           action_configuration[key][:info]
       end
 
-
       def key_with_default_fallback(key)
         action_configuration[key] || default_configuration[key]
       end
 
-
       def presenter_title
         presenter && presenter.title
       end
 
-
       #
       # Returns the relative path from this endpoint's controller to this
       # endpoint's declared presenter.