brainstem 1.4.1 → 2.0.0

data/lib/brainstem/api_docs/endpoint_collection.rb

@@ -7,7 +7,6 @@ module Brainstem
     class EndpointCollection < AbstractCollection
       include Concerns::Formattable
 
-
       def find_from_route(route)
         find do |endpoint|
           endpoint.path == route[:path] &&
@@ -18,7 +17,6 @@ module Brainstem
 
       alias_method :find_by_route, :find_from_route
 
-
       def create_from_route(route, controller)
         Endpoint.new(atlas) do |ep|
           ep.path             = route[:path]
@@ -29,27 +27,22 @@ module Brainstem
         end.tap { |endpoint| self.<< endpoint }
       end
 
-
       def only_documentable
         self.class.with_members(atlas, reject(&:nodoc?))
       end
 
-
       def with_declared_presented_class
         self.class.with_members(atlas, reject { |m| m.declared_presented_class.nil? })
       end
 
-
       def sorted
         self.class.with_members(atlas, sort)
       end
 
-
       def with_actions_in_controller(const)
         self.class.with_members(atlas, reject { |m| !const.method_defined?(m.action) })
       end
 
-
       def sorted_with_actions_in_controller(const)
         with_actions_in_controller(const).sorted
       end

data/lib/brainstem/api_docs/formatters/abstract_formatter.rb

@@ -46,12 +46,10 @@ module Brainstem
           new(*args).call
         end
 
-
         def initialize(*args)
           super args.last || {}
         end
 
-
         #
         # Override to transform atlas data into serialized format.
         #

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

@@ -17,14 +17,12 @@ module Brainstem
             ]
           end
 
-
           attr_accessor :controller,
                         :include_actions,
                         :output
 
           alias_method :include_actions?, :include_actions
 
-
           def initialize(controller, options = {})
             self.controller      = controller
             self.output          = ""
@@ -32,7 +30,6 @@ module Brainstem
             super options
           end
 
-
           def call
             return output if controller.nodoc?
             format_title!
@@ -40,22 +37,18 @@ module Brainstem
             format_actions!
           end
 
-
           #####################################################################
           private
           #####################################################################
 
-
           def format_title!
             output << md_h2(controller.title)
           end
 
-
           def format_description!
             output << md_p(controller.description) unless controller.description.empty?
           end
 
-
           def format_actions!
             return unless include_actions?
 
@@ -71,6 +64,5 @@ module Brainstem
   end
 end
 
-
-Brainstem::ApiDocs::FORMATTERS[:controller][:markdown] = \
+Brainstem::ApiDocs::FORMATTERS[:controller][:markdown] =
   Brainstem::ApiDocs::Formatters::Markdown::ControllerFormatter.method(:call)

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

@@ -23,24 +23,20 @@ module Brainstem
             super options
           end
 
-
           attr_accessor :endpoint_collection,
                         :zero_text,
                         :output
 
-
           def valid_options
             super | [ :zero_text ]
           end
 
-
           def call
             format_endpoints!
             format_zero_text! if output.empty?
             output
           end
 
-
           #####################################################################
           private
           #####################################################################
@@ -52,12 +48,10 @@ module Brainstem
               .reject(&:empty?)
           end
 
-
           def format_endpoints!
             output << all_formatted_endpoints.join(md_hr)
           end
 
-
           def format_zero_text!
             output << zero_text
           end
@@ -67,7 +61,5 @@ module Brainstem
   end
 end
 
-
-
-Brainstem::ApiDocs::FORMATTERS[:endpoint_collection][:markdown] = \
+Brainstem::ApiDocs::FORMATTERS[:endpoint_collection][:markdown] =
   Brainstem::ApiDocs::Formatters::Markdown::EndpointCollectionFormatter.method(:call)

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

@@ -14,12 +14,10 @@ module Brainstem
           include Helper
           extend Forwardable
 
-
           ################################################################################
           # Public API
           ################################################################################
 
-
           def initialize(endpoint, options = {})
             self.endpoint = endpoint
             self.output   = ""
@@ -27,11 +25,9 @@ module Brainstem
             super options
           end
 
-
           attr_accessor :endpoint,
                         :output
 
-
           def call
             return output if endpoint.nodoc?
 
@@ -44,14 +40,12 @@ module Brainstem
             output
           end
 
-
           ################################################################################
           private
           ################################################################################
 
           delegate :controller => :endpoint
 
-
           #
           # Formats the title as given, falling back to the humanized action
           # name.
@@ -60,7 +54,6 @@ module Brainstem
             output << md_h4(endpoint.title)
           end
 
-
           #
           # Formats the description if given.
           #
@@ -68,7 +61,6 @@ module Brainstem
             output << md_p(endpoint.description) unless endpoint.description.empty?
           end
 
-
           #
           # Formats the actual URI and stated HTTP methods.
           #
@@ -78,7 +70,6 @@ module Brainstem
             output << md_code("#{http_methods} #{path}")
           end
 
-
           #
           # Formats each parameter.
           #
@@ -118,18 +109,15 @@ 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.
+          # @option options [Boolean] :required
+          # @option options [Boolean] :legacy
+          # @option options [Boolean] :recursive
+          # @option options [String, Symbol] :only Deprecated: use +actions+ block instead
+          # @option options [String] :info the doc string for the param
+          # @option options [String] :type The type of the field. e.g. string, integer, boolean, array, hash
+          # @option options [String] :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
+          # @param [Integer] indent how many levels the output should be indented from normal
           #
           def parameter_with_indent_level(title, options = {}, indent = 0)
             options = options.dup
@@ -149,12 +137,22 @@ module Brainstem
             md_li(text, indent)
           end
 
-
           #
           # Formats the data model for the action.
           #
           def format_presents!
-            if endpoint.presenter
+            if endpoint.custom_response.present?
+              response_configuration_tree = endpoint.custom_response_configuration_tree
+              response_structure_config = response_configuration_tree[:_config]
+
+              output << md_p(format_custom_response_message(response_structure_config))
+              output << md_ul do
+                response_configuration_tree.except(:_config).inject("") do |buff, (param_name, param_config)|
+                  buff << format_param_tree!("", param_name, param_config)
+                  buff
+                end
+              end
+            elsif endpoint.presenter
               output << md_h5("Data Model")
 
               link = md_a(endpoint.presenter_title, endpoint.relative_presenter_path_from_controller(:markdown))
@@ -163,12 +161,29 @@ module Brainstem
               end
             end
           end
+
+          def format_custom_response_message(response_config)
+            result = "The resulting JSON is "
+            result << case response_config[:type]
+              when "array"
+                if response_config[:item_type] == "hash"
+                  "an array of objects with the following properties"
+                else
+                  "an array of #{response_config[:item_type].pluralize}"
+                end
+              when "hash"
+                "a hash with the following properties"
+              else
+                "a #{response_config[:type]}"
+            end
+
+            result
+          end
         end
       end
     end
   end
 end
 
-
-Brainstem::ApiDocs::FORMATTERS[:endpoint][:markdown] = \
+Brainstem::ApiDocs::FORMATTERS[:endpoint][:markdown] =
   Brainstem::ApiDocs::Formatters::Markdown::EndpointFormatter.method(:call)

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

@@ -10,67 +10,54 @@ module Brainstem
             "# #{text}\n\n"
           end
 
-
           def md_h2(text)
             "## #{text}\n\n"
           end
 
-
           def md_h3(text)
             "### #{text}\n\n"
           end
 
-
           def md_h4(text)
             "#### #{text}\n\n"
           end
 
-
           def md_h5(text)
             "##### #{text}\n\n"
           end
 
-
           def md_strong(text)
             "**#{text}**"
           end
 
-
           def md_hr
             "-----\n\n"
           end
 
-
           def md_p(text)
             text + "\n\n"
           end
 
-
           def md_code(text, lang = "")
             "```#{lang}\n#{text}\n```\n\n"
           end
 
-
           def md_inline_code(text)
             "`#{text}`"
           end
 
-
           def md_ul(&block)
             (instance_eval(&block) || "") + "\n\n"
           end
 
-
           def md_li(text, indent_level = 0)
             "#{' ' * (indent_level * 4)}- #{text}\n"
           end
 
-
           def md_a(text, link)
             "[#{text}](#{link})"
           end
 
-
           def md_inline_type(type, item_type = nil)
             return "" if type.blank?
 

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

@@ -9,18 +9,15 @@ module Brainstem
         class PresenterFormatter < AbstractFormatter
           include Helper
 
-
           def initialize(presenter, options = {})
             self.presenter = presenter
             self.output    = ""
             super options
           end
 
-
           attr_accessor :presenter,
                         :output
 
-
           def call
             return output if presenter.nodoc?
 
@@ -35,7 +32,6 @@ module Brainstem
             output
           end
 
-
           #####################################################################
           private
           #####################################################################
@@ -44,7 +40,6 @@ module Brainstem
             output << md_h4(presenter.title)
           end
 
-
           def format_brainstem_keys!
             text = "Top-level key: "
             text << presenter.brainstem_keys
@@ -54,12 +49,10 @@ module Brainstem
             output << md_p(text)
           end
 
-
           def format_description!
             output << md_p(presenter.description) unless presenter.description.empty?
           end
 
-
           def format_field_leaf(field, indent_level)
             text = md_inline_code(field.name.to_s)
             text << md_inline_type(field.type, field.options[:item_type])
@@ -81,7 +74,6 @@ module Brainstem
             text.chomp!
           end
 
-
           def format_field_branch(branch, indent_level = 0)
             branch.inject("") do |buffer, (name, field)|
               if nested_field?(field)
@@ -94,12 +86,10 @@ module Brainstem
             end
           end
 
-
           def nested_field?(field)
             field.respond_to?(:configuration)
           end
 
-
           def format_fields!
             output << md_h5("Fields")
 
@@ -113,7 +103,6 @@ module Brainstem
             end
           end
 
-
           def format_filters!
             if presenter.valid_filters.any?
               output << md_h5("Filters")
@@ -141,7 +130,6 @@ module Brainstem
             end
           end
 
-
           def format_sort_orders!
             if presenter.valid_sort_orders.any?
               output << md_h5("Sort Orders")
@@ -169,34 +157,33 @@ module Brainstem
             end
           end
 
-
           def format_associations!
-            if presenter.valid_associations.any?
-              output << md_h5("Associations")
-
-              output << "Association Name | Associated Class | Description\n"
-              output << " --------------  |  --------------  |  ----------\n"
-
-              output << presenter.valid_associations.inject("") do |buffer, (_, association)|
-                link = presenter.link_for_association(association)
-                if link
-                  link = md_a(association.target_class, link)
-                else
-                  link = association.target_class.to_s
-                end
+            return if presenter.valid_associations.empty?
 
-                desc = association.description.to_s
-                if association.options && association.options[:restrict_to_only]
-                  desc += "." unless desc =~ /\.\s*\z/
-                  desc += "  Restricted to queries using the #{md_inline_code("only")} parameter."
-                  desc.strip!
-                end
+            output << md_h5("Associations")
 
-                buffer << md_inline_code(association.name) + " | " + link + " | " + desc + "\n"
+            output << "Association Name | Associated Class | Description\n"
+            output << " --------------  |  --------------  |  ----------\n"
+
+            output << presenter.valid_associations.inject("") do |buffer, (_, association)|
+              link = presenter.link_for_association(association)
+              if link
+                link = md_a(association.target_class, link)
+              else
+                link = association.target_class.to_s
               end
 
-              output << "\n"
+              desc = association.description.to_s
+              if association.options && association.options[:restrict_to_only]
+                desc += "." unless desc =~ /\.\s*\z/
+                desc += "  Restricted to queries using the #{md_inline_code("only")} parameter."
+                desc.strip!
+              end
+
+              buffer << md_inline_code(association.name) + " | " + link + " | " + desc + "\n"
             end
+
+            output << "\n"
           end
         end
       end
@@ -204,5 +191,5 @@ module Brainstem
   end
 end
 
-Brainstem::ApiDocs::FORMATTERS[:presenter][:markdown] = \
+Brainstem::ApiDocs::FORMATTERS[:presenter][:markdown] =
   Brainstem::ApiDocs::Formatters::Markdown::PresenterFormatter.method(:call)