brainstem 2.0.0 → 2.1.0

data/lib/brainstem/api_docs/endpoint_collection.rb

@@ -7,6 +7,14 @@ module Brainstem
     class EndpointCollection < AbstractCollection
       include Concerns::Formattable
 
+      attr_accessor :include_internal
+
+      def valid_options
+        super | [
+          :include_internal
+        ]
+      end
+
       def find_from_route(route)
         find do |endpoint|
           endpoint.path == route[:path] &&
@@ -18,7 +26,7 @@ module Brainstem
       alias_method :find_by_route, :find_from_route
 
       def create_from_route(route, controller)
-        Endpoint.new(atlas) do |ep|
+        Endpoint.new(atlas, include_internal: self.include_internal) do |ep|
           ep.path             = route[:path]
           ep.http_methods     = route[:http_methods]
           ep.controller       = controller

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

@@ -18,7 +18,7 @@ module Brainstem
             name.underscore.titleize.strip
           end
 
-          def format_description(description)
+          def format_sentence(description)
             return '' if description.blank?
 
             desc = description.to_s.strip.tap { |desc| desc[0] = desc[0].upcase }
@@ -32,11 +32,10 @@ module Brainstem
             description.strip.tap { |desc| desc[0] = desc[0].downcase }
           end
 
-          # TODO: multi nested
           def type_and_format(type, item_type = nil)
             result = case type.to_s.downcase
               when 'array'
-                { 'type' => 'array', 'items' => { 'type' => item_type.presence || 'string' } }
+                { 'type' => 'array', 'items' => type_and_format(item_type.presence || 'string') }
               else
                 TYPE_INFO[type.to_s]
             end
@@ -44,19 +43,23 @@ module Brainstem
           end
 
           TYPE_INFO = {
-            'string'       => { 'type' => 'string'                           },
-            'boolean'      => { 'type' => 'boolean'                          },
-            'integer'      => { 'type' => 'integer', 'format' => 'int32'	   },
-            'long'         => { 'type' => 'integer', 'format' => 'int64'	   },
-            'float'        => { 'type' => 'number',  'format' => 'float'     },
-            'double'       => { 'type' => 'number',  'format' => 'double'    },
-            'byte'         => { 'type' => 'string',  'format' => 'byte'      },
-            'binary'       => { 'type' => 'string',  'format' => 'binary'    },
-            'date'         => { 'type' => 'string',  'format' => 'date'      },
-            'datetime'     => { 'type' => 'string',  'format' => 'date-time' },
-            'password'     => { 'type' => 'string',  'format' => 'password'  },
-            'id'           => { 'type' => 'integer', 'format' => 'int32'	   },
-            'decimal'      => { 'type' => 'number',  'format' => 'float'     },
+            'string'   => { 'type' => 'string'                           },
+            'boolean'  => { 'type' => 'boolean'                          },
+            'integer'  => { 'type' => 'integer', 'format' => 'int32'	   },
+            'long'     => { 'type' => 'integer', 'format' => 'int64'	   },
+            'float'    => { 'type' => 'number',  'format' => 'float'     },
+            'double'   => { 'type' => 'number',  'format' => 'double'    },
+            'byte'     => { 'type' => 'string',  'format' => 'byte'      },
+            'binary'   => { 'type' => 'string',  'format' => 'binary'    },
+            'date'     => { 'type' => 'string',  'format' => 'date'      },
+            'datetime' => { 'type' => 'string',  'format' => 'date-time' },
+            'password' => { 'type' => 'string',  'format' => 'password'  },
+            'id'       => { 'type' => 'integer', 'format' => 'int32'	   },
+            'decimal'  => { 'type' => 'number',  'format' => 'float'     },
+            'csv'      => { 'type' => 'string',  'collectionFormat' => 'csv'   },
+            'ssv'      => { 'type' => 'string',  'collectionFormat' => 'ssv'   },
+            'tsv'      => { 'type' => 'string',  'collectionFormat' => 'tsv'   },
+            'pipes'    => { 'type' => 'string',  'collectionFormat' => 'pipes' },
           }
           private_constant :TYPE_INFO
         end

data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint/param_definitions_formatter.rb

@@ -3,6 +3,7 @@ require 'active_support/core_ext/hash/compact'
 require 'active_support/inflector'
 require 'brainstem/api_docs/formatters/abstract_formatter'
 require 'brainstem/api_docs/formatters/open_api_specification/helper'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/field_definitions/endpoint_param_formatter'
 require 'brainstem/api_docs/formatters/markdown/helper'
 
 #
@@ -30,17 +31,19 @@ module Brainstem
               def call
                 format_path_params!
 
-                if endpoint.action == 'index'
-                  format_pagination_params!
-                  format_search_param!
-                  format_only_param!
-                  format_sort_order_params!
-                  format_filter_params!
-                end
+                if presenter
+                  if endpoint.action == 'index'
+                    format_pagination_params!
+                    format_search_param!
+                    format_only_param!
+                    format_sort_order_params!
+                    format_filter_params!
+                  end
 
-                if http_method != 'delete'
-                  format_optional_params!
-                  format_include_params!
+                  if http_method != 'delete'
+                    format_optional_params!
+                    format_include_params!
+                  end
                 end
 
                 format_query_params!
@@ -104,8 +107,12 @@ module Brainstem
               def format_sort_order_params!
                 return if presenter.nil? || (valid_sort_orders = presenter.valid_sort_orders).empty?
 
-                sort_orders = valid_sort_orders.map { |sort_name, _|
-                  [md_inline_code("#{sort_name}:asc"), md_inline_code("#{sort_name}:desc")]
+                sort_orders = valid_sort_orders.map { |sort_name, sort_config|
+                  if sort_config[:direction]
+                    [md_inline_code("#{sort_name}:asc"), md_inline_code("#{sort_name}:desc")]
+                  else
+                    md_inline_code(sort_name)
+                  end
                 }.flatten.sort
 
                 description = <<-DESC.strip_heredoc
@@ -160,7 +167,7 @@ module Brainstem
                   text = md_inline_code(association.name)
                   text += " (#{ association.target_class.to_s })"
 
-                  desc = format_description(association.description)
+                  desc = format_sentence(association.description)
                   if association.options && association.options[:restrict_to_only]
                     desc += "  Restricted to queries using the #{md_inline_code("only")} parameter."
                   end
@@ -208,13 +215,15 @@ module Brainstem
                   'in'          => 'query',
                   'name'        => param_name.to_s,
                   'required'    => param_config[:required],
-                  'description' => format_description(param_config[:info]).presence,
+                  'description' => format_sentence(param_config[:info]).presence,
                 }.merge(type_data).compact
               end
 
               def format_body_params!
-                formatted_body_params = format_body_params
-                return if formatted_body_params.blank?
+                properties, additional_properties = split_properties(endpoint.params_configuration_tree)
+                formatted_body_params = format_field_properties(properties)
+                formatted_dynamic_key_params = format_field_properties(additional_properties)
+                return if formatted_body_params.blank? && formatted_dynamic_key_params.blank?
 
                 output << {
                   'in'          => 'body',
@@ -222,82 +231,45 @@ module Brainstem
                   'name'        => 'body',
                   'schema'      => {
                     'type'       => 'object',
-                    'properties' => formatted_body_params
-                  },
+                    'properties' => formatted_body_params,
+                    'additionalProperties' => formatted_dynamic_key_params,
+                  }.with_indifferent_access.reject { |_, v| v.blank? },
                 }
               end
 
-              def format_body_params
-                ActiveSupport::HashWithIndifferentAccess.new.tap do |body_params|
-                  endpoint.params_configuration_tree.each do |param_name, param_config|
-                    next if nested_properties(param_config).blank?
-
-                    body_params[param_name] = format_parent_param(param_name, param_config)
-                  end
-                end
-              end
-
-              def format_parent_param(param_name, param_data)
-                param_config = param_data[:_config]
-                result = case param_config[:type]
-                  when 'hash'
-                    {
-                      type:        'object',
-                      title:       param_name.to_s,
-                      description: format_description(param_config[:info]),
-                      properties:  format_param_branch(nested_properties(param_data))
-                    }
-                  when 'array'
-                    {
-                      type:        'array',
-                      title:       param_name.to_s,
-                      description: format_description(param_config[:info]),
-                      items: {
-                        type: 'object',
-                        properties: format_param_branch(nested_properties(param_data))
-                      }
-                    }
+              def split_properties(field_properties)
+                split_properties = field_properties.each_with_object({ properties: {}, additional_properties: {} }) do |(field_name, field_config), acc|
+                  if field_config[:_config][:dynamic_key]
+                    acc[:additional_properties][field_name] = field_config
                   else
-                    raise "Unknown Brainstem body param encountered(#{param_config[:type]}) for field #{param_name}"
+                    acc[:properties][field_name] = field_config
+                  end
                 end
 
-                result.with_indifferent_access.reject { |_, v| v.blank? }
+                [split_properties[:properties], split_properties[:additional_properties]]
               end
 
-              def format_param_branch(branch)
-                branch.inject(ActiveSupport::HashWithIndifferentAccess.new) do |buffer, (param_name, param_data)|
-                  nested_properties = nested_properties(param_data)
-                  param_config = param_data[:_config]
-
-                  branch_schema = if nested_properties.present?
-                    case param_config[:type].to_s
-                      when 'hash'
-                        { type: 'object', properties: format_param_branch(nested_properties) }
-                      when 'array'
-                        {
-                          type: 'array',
-                          items: { type: 'object', properties: format_param_branch(nested_properties) }
-                        }
-                      else
-                        raise "Unknown Brainstem Param type encountered(#{param_config[:type]}) for param #{param_name}"
-                    end
+              def format_field_properties(branches)
+                branches.inject(ActiveSupport::HashWithIndifferentAccess.new) do |buffer, (field_name, field_config)|
+                  if dynamic_key_field?(field_config)
+                    formatted_field('Dynamic Key Field', field_config)
                   else
-                    param_data = type_and_format(param_config[:type].to_s, param_config[:item_type])
-
-                    if param_data.blank?
-                      raise "Unknown Brainstem Param type encountered(#{param_config[:type]}) for param #{param_name}"
-                    end
-
-                    param_data
+                    buffer[field_name.to_s] = formatted_field(field_name, field_config) if nested_properties(field_config).present?
+                    buffer
                   end
+                end
+              end
 
-                  buffer[param_name.to_s] = {
-                    title:       param_name.to_s,
-                    description: format_description(param_config[:info])
-                  }.merge(branch_schema).reject { |_, v| v.blank? }
+              def dynamic_key_field?(param_config)
+                param_config[:_config][:dynamic_key].presence
+              end
 
-                  buffer
-                end
+              def formatted_field(param_name, param_data)
+                Brainstem::ApiDocs::FORMATTERS[:endpoint_param][:oas_v2].call(
+                  endpoint,
+                  param_name,
+                  param_data
+                )
               end
             end
           end

data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/endpoint/response_definitions_formatter.rb

@@ -2,6 +2,7 @@ require 'active_support/core_ext/hash/except'
 require 'active_support/inflector'
 require 'brainstem/api_docs/formatters/abstract_formatter'
 require 'brainstem/api_docs/formatters/open_api_specification/helper'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/field_definitions/response_field_formatter'
 require 'forwardable'
 
 #
@@ -72,41 +73,70 @@ module Brainstem
               def format_schema_response!
                 return if presenter.nil?
 
-                brainstem_key = presenter.brainstem_keys.first
-                model_klass   = presenter.target_class
-
                 output.merge! '200' => {
                   description: success_response_description,
                   schema: {
+                    type: 'object',
+                    properties: properties
+                  }
+                }
+              end
+
+              def properties
+                brainstem_key = presenter.brainstem_keys.first
+                model_klass = presenter.target_class
+
+                {
+                  count: type_and_format('integer'),
+                  meta: {
                     type: 'object',
                     properties: {
                       count: type_and_format('integer'),
-                      meta: {
-                        type: 'object',
-                        properties: {
-                          count:       type_and_format('integer'),
-                          page_count:  type_and_format('integer'),
-                          page_number: type_and_format('integer'),
-                          page_size:   type_and_format('integer'),
-                        }
-                      },
-                      results: {
-                        type: 'array',
-                        items: {
-                          type: 'object',
-                          properties: {
-                            key: type_and_format('string'),
-                            id:  type_and_format('string')
-                          }
-                        }
-                      },
-                      brainstem_key => {
-                        type: 'object',
-                        additionalProperties: {
-                          '$ref' => "#/definitions/#{model_klass}"
-                        }
+                      page_count: type_and_format('integer'),
+                      page_number: type_and_format('integer'),
+                      page_size: type_and_format('integer'),
+                    }
+                  },
+                  results: {
+                    type: 'array',
+                    items: {
+                      type: 'object',
+                      properties: {
+                        key: type_and_format('string'),
+                        id: type_and_format('string')
                       }
                     }
+                  },
+                  brainstem_key => object_reference(model_klass)
+                }.merge(associated_properties)
+              end
+
+              def associated_properties
+                presenter.valid_associations.each_with_object({}) do |(_key, association), obj|
+                  if association.polymorphic?
+                    associated_klasses = association.polymorphic_classes || []
+                    associated_klasses.each do |assoc|
+                      association_reference(assoc, obj)
+                    end
+                  else
+                    association_reference(association.target_class, obj)
+                  end
+                end
+              end
+
+              def association_reference(target_class, obj)
+                assoc_presenter = presenter.find_by_class(target_class)
+                brainstem_key = assoc_presenter.brainstem_keys.first
+                return if assoc_presenter.nodoc?
+
+                obj[brainstem_key] = object_reference(target_class)
+              end
+
+              def object_reference(klass)
+                {
+                  type: 'object',
+                  additionalProperties: {
+                    '$ref' => "#/definitions/#{klass}"
                   }
                 }
               end
@@ -124,66 +154,16 @@ module Brainstem
               def format_custom_response!
                 output.merge! '200' => {
                   description: success_response_description,
-                  schema: format_response(endpoint.custom_response_configuration_tree)
+                  schema: format_response!
                 }
               end
 
-              def format_response(response_tree)
-                response_config   = response_tree[:_config]
-                response_branches = response_tree.except(:_config)
-
-                format_response_field(response_config, response_branches)
-              end
-
-              def format_response_field(field_config, field_branches)
-                if field_branches.present?
-                  formed_nested_field(field_config, field_branches)
-                else
-                  format_response_leaf(field_config)
-                end
-              end
-
-              def format_response_leaf(field_config)
-                field_data = type_and_format(field_config[:type], field_config[:item_type])
-
-                unless field_data
-                  raise "Unknown Brainstem Field type encountered(#{field_config[:type]}) for field #{field_config[:name]}"
-                end
-
-                field_data.merge!(description: format_description(field_config[:info])) if field_config[:info].present?
-                field_data
-              end
-
-              def formed_nested_field(field_config, field_branches)
-                result = case field_config[:type]
-                  when 'hash'
-                    {
-                      type: 'object',
-                      description: format_description(field_config[:info]),
-                      properties: format_response_branches(field_branches)
-                    }
-                  when 'array'
-                    {
-                      type: 'array',
-                      description: format_description(field_config[:info]),
-                      items: {
-                        type: 'object',
-                        properties: format_response_branches(field_branches)
-                      }
-                    }
-                end
-
-                result.with_indifferent_access.reject { |_, v| v.blank? }
-              end
-
-              def format_response_branches(branches)
-                branches.inject(ActiveSupport::HashWithIndifferentAccess.new) do |buffer, (field_name, field_config)|
-                  config   = field_config[:_config]
-                  branches = field_config.except(:_config)
-
-                  buffer[field_name.to_s] = format_response_field(config, branches)
-                  buffer
-                end
+              def format_response!
+                Brainstem::ApiDocs::FORMATTERS[:response_field][:oas_v2].call(
+                  endpoint,
+                  'schema',
+                  endpoint.custom_response_configuration_tree
+                )
               end
             end
           end

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

@@ -104,7 +104,7 @@ module Brainstem
             #
             def format_optional_info!
               info = {
-                description:    format_description(description),
+                description:    format_sentence(description),
                 operation_id:   endpoint.operation_id,
                 consumes:       endpoint.consumes,
                 produces:       endpoint.produces,