brainstem 2.0.0 → 2.1.0

data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/field_definitions/endpoint_param_formatter.rb

@@ -0,0 +1,39 @@
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/field_definitions/response_field_formatter'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          module FieldDefinitions
+            class EndpointParamFormatter < ResponseFieldFormatter
+              def initialize(endpoint, param_name, param_tree)
+                @endpoint = endpoint
+                @param_name = param_name
+                @param_tree = param_tree
+              end
+
+              def format_object_field(field_config, field_properties, include_description = true)
+                super(field_config, field_properties, include_description).tap do |field_schema|
+                  if (required_props = required_properties(field_properties)).present?
+                    field_schema[:required] = required_props
+                  end
+                end
+              end
+
+              def required_properties(field_properties)
+                field_properties.select do |_, property_data|
+                  !property_data[:_config][:dynamic_key] && property_data[:_config][:required]
+                end.keys
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:endpoint_param][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::FieldDefinitions::EndpointParamFormatter.method(:call)
+

data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/field_definitions/presenter_field_formatter.rb

@@ -0,0 +1,147 @@
+require 'brainstem/api_docs'
+require 'brainstem/api_docs/formatters/abstract_formatter'
+require 'brainstem/api_docs/formatters/open_api_specification/helper'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          module FieldDefinitions
+            class PresenterFieldFormatter < AbstractFormatter
+              include Helper
+              
+              def initialize(presenter, field)
+                @presenter = presenter
+                @field = field
+              end
+
+              def format
+                format_field(@field)
+              end
+              alias_method :call, :format
+
+              private
+              
+              attr_reader :presenter
+
+              def has_properties?(field)
+                field.respond_to?(:configuration)
+              end
+
+              def format_field(field)
+                if field.options[:nested_levels]
+                  format_nested_array_field(field)
+                elsif has_properties?(field)
+                  format_nested_field(field)
+                else
+                  format_simple_field(field)
+                end
+              end
+
+              def format_nested_array_field(field)
+                field_properties_data, nested_levels = format_array_items(field)
+
+                format_nested_array_parent(nested_levels, field_properties_data, format_description(field))
+              end
+
+              def format_array_items(field)
+                field_nested_levels = field.options[:nested_levels]
+
+                if has_properties?(field)
+                  [format_nested_field(field, false), field_nested_levels - 1]
+                else
+                  [type_and_format(field.options[:item_type]), field_nested_levels]
+                end
+              end
+
+              def format_nested_array_parent(nested_level, formatted_data, description = nil)
+                if nested_level == 1
+                  {
+                    'type' => 'array',
+                    'description' => description,
+                    'items' => formatted_data
+                  }
+                else
+                  {
+                    'type' => 'array',
+                    'description' => description,
+                    'items' => format_nested_array_parent(nested_level - 1, formatted_data)
+                  }
+                end.with_indifferent_access.reject { |_, v| v.blank? }
+              end
+
+              def format_nested_field(field, include_description = true)
+                case field.type
+                  when 'hash'
+                    format_object_field(field, include_description)
+                  when 'array'
+                    {
+                      type: 'array',
+                      description: include_description && format_description(field),
+                      items: format_object_field(field, false)
+                    }
+                end.with_indifferent_access.reject { |_, v| v.blank? }
+              end
+
+              def format_object_field(field, include_description = true)
+                {
+                  type: 'object',
+                  description: include_description && format_description(field),
+                  properties: format_field_properties(field.to_h),
+                }.with_indifferent_access.reject { |_, v| v.blank? }
+              end
+
+              def format_simple_field(field)
+                field_data = type_and_format(field.type) || raise(invalid_type_error_message(field))
+                field_data.merge!(description: format_description(field))
+                field_data.with_indifferent_access.reject { |_, v| v.blank? }
+              end
+              
+              def invalid_type_error_message(field)
+                <<-MSG.strip_heredoc
+                  Unknown Brainstem Field type encountered(#{field.type}) for field #{field.name}
+                  in #{presenter.target_class.to_s}.
+                MSG
+              end
+
+              def format_field_properties(branches)
+                branches.inject(ActiveSupport::HashWithIndifferentAccess.new) do |buffer, (field_name, field)|
+                  buffer[field_name.to_s] = format_field(field)
+                  buffer
+                end
+              end
+
+              def format_description(field)
+                field_description = format_sentence(field.description) || ''
+                field_description << format_conditional_description(field.options)
+                if field.optional?
+                  field_description << "\nOnly returned when requested through the optional_fields param.\n"
+                end
+                field_description.try(:chomp!)
+                field_description
+              end
+
+              def format_conditional_description(field_options)
+                return '' if field_options[:if].blank?
+
+                conditions = field_options[:if]
+                  .reject { |cond| presenter.conditionals[cond].options[:nodoc] }
+                  .map    { |cond| uncapitalize(presenter.conditionals[cond].description) }
+                  .delete_if(&:empty?)
+                  .uniq
+                  .to_sentence
+
+                conditions.present? ? "\nVisible when #{conditions}.\n" : ''
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:presenter_field][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::FieldDefinitions::PresenterFieldFormatter.method(:call)
+

data/lib/brainstem/api_docs/formatters/open_api_specification/version_2/field_definitions/response_field_formatter.rb

@@ -0,0 +1,146 @@
+require 'brainstem/api_docs'
+require 'brainstem/api_docs/formatters/abstract_formatter'
+require 'brainstem/api_docs/formatters/open_api_specification/helper'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          module FieldDefinitions
+            class ResponseFieldFormatter < AbstractFormatter
+              include Helper
+
+              def initialize(endpoint, param_name, param_tree)
+                @endpoint = endpoint
+                @param_name = param_name
+                @param_tree = param_tree
+              end
+
+              def format
+                field_config = @param_tree[:_config]
+                field_properties = @param_tree.except(:_config)
+  
+                format_field(field_config, field_properties)
+              end
+              alias_method :call, :format
+
+              private
+
+              def format_field(field_config, field_branches)
+                if field_config[:nested_levels]
+                  format_nested_array_field(field_config, field_branches)
+                elsif field_branches.present?
+                  format_nested_field(field_config, field_branches)
+                else
+                  format_simple_field(field_config)
+                end
+              end
+
+              def format_nested_array_field(field_config, field_properties)
+                field_properties_data, nested_levels = format_array_items(field_config, field_properties)
+                
+                format_nested_array_parent(nested_levels, field_properties_data)
+              end
+              
+              def format_array_items(field_config, field_properties)
+                field_nested_levels = field_config[:nested_levels]
+                
+                if field_properties.present?
+                  [format_nested_field(field_config, field_properties), field_nested_levels - 1]
+                else
+                  [type_and_format(field_config[:item_type]), field_nested_levels]
+                end
+              end
+
+              def format_nested_array_parent(nested_level, formatted_data)
+                if nested_level == 1
+                  {
+                    'type' => 'array',
+                    'items' => formatted_data
+                  }
+                else
+                  {
+                    'type' => 'array',
+                    'items' => format_nested_array_parent(nested_level - 1, formatted_data)
+                  }
+                end
+              end
+
+              def format_nested_field(field_config, field_properties)
+                case field_config[:type]
+                  when 'hash'
+                    format_object_field(field_config, field_properties)
+                  when 'array'
+                    {
+                      type: 'array',
+                      description: format_description(field_config),
+                      items: format_object_field(field_config, field_properties, false)
+                    }
+                end.with_indifferent_access.reject { |_, v| v.blank? }
+              end
+
+              def format_object_field(field_config, field_properties, include_description = true)
+                properties, additional_properties = split_properties(field_properties)
+
+                {
+                  type: 'object',
+                  description: include_description && format_description(field_config),
+                  properties: format_field_properties(properties),
+                  additionalProperties: format_field_properties(additional_properties),
+                }.with_indifferent_access.reject { |_, v| v.blank? }
+              end
+
+              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
+                    acc[:properties][field_name] = field_config
+                  end
+                end
+
+                [split_properties[:properties], split_properties[:additional_properties]]
+              end
+
+              def format_simple_field(field_config)
+                field_data = type_and_format(field_config[:type], field_config[:item_type])
+                raise(invalid_type_error_message(field_config)) unless field_data
+                field_data.merge!(description: format_sentence(field_config[:info])) if field_config[:info].present?
+                field_data
+              end
+
+              def invalid_type_error_message(field_config)
+                <<-MSG.strip_heredoc
+                  Unknown Brainstem Field type encountered(#{field_config[:type]}) for field #{field_config[:name]}
+                  in #{@endpoint.controller_name} for #{@endpoint.action} action. 
+                MSG
+              end
+
+              def format_field_properties(branches)
+                branches.inject(ActiveSupport::HashWithIndifferentAccess.new) do |buffer, (field_name, field_config)|
+                  config = field_config[:_config]
+                  branches = field_config.except(:_config)
+
+                  if config[:dynamic_key]
+                    format_field(config, branches)
+                  else
+                    buffer[field_name.to_s] = format_field(config, branches)
+                    buffer
+                  end
+                end
+              end
+              
+              def format_description(field_config)
+                format_sentence(field_config[:info])
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:response_field][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::FieldDefinitions::ResponseFieldFormatter.method(:call)

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

@@ -1,6 +1,7 @@
 require 'active_support/core_ext/string/inflections'
 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/presenter_field_formatter'
 
 module Brainstem
   module ApiDocs
@@ -30,6 +31,7 @@ module Brainstem
               format_description!
               format_type!
               format_fields!
+              sort_properties!
 
               output.merge!(presenter.target_class => definition.reject {|_, v| v.blank?})
             end
@@ -42,8 +44,16 @@ module Brainstem
               definition.merge! title: presenter_title(presenter)
             end
 
+            def sort_properties!
+              return if definition[:properties].blank?
+
+              definition[:properties] = definition[:properties].sort.each_with_object({}) do |(key, val), obj|
+                obj[key] = val
+              end
+            end
+
             def format_description!
-              definition.merge! description: format_description(presenter.description)
+              definition.merge! description: format_sentence(presenter.description)
             end
 
             def format_type!
@@ -51,75 +61,63 @@ module Brainstem
             end
 
             def format_fields!
-              return unless presenter.valid_fields.any?
+              return unless presenter.valid_fields.any? || presenter.valid_associations.any?
 
-              definition.merge! properties: format_field_branch(presenter.valid_fields)
+              properties = format_field_branch(presenter.valid_fields)
+              with_associations = format_field_associations(properties)
+
+              definition.merge! properties: with_associations
             end
 
             def format_field_branch(branch)
-              branch.inject(ActiveSupport::HashWithIndifferentAccess.new) do |buffer, (name, field)|
-                if nested_field?(field)
-                  buffer[name.to_s] = case field.type
-                    when 'hash'
-                      {
-                        type: 'object',
-                        properties: format_field_branch(field.to_h)
-                      }.with_indifferent_access
-                    when 'array'
-                      {
-                        type: 'array',
-                        items: {
-                          type: 'object',
-                          properties: format_field_branch(field.to_h)
-                        }
-                      }.with_indifferent_access
-                    else
-                      raise "Unknown Brainstem Field type encountered(#{field.type}) for field #{name}"
-                  end
-                else
-                  buffer[name.to_s] = format_field_leaf(field)
-                end
-
-                buffer
+              branch.each_with_object(ActiveSupport::HashWithIndifferentAccess.new) do |(name, field), buffer|
+                buffer[name.to_s] = format_field(field)
               end
             end
 
-            def nested_field?(field)
-              field.respond_to?(:configuration)
-            end
+            def format_field_associations(properties)
+              presenter.valid_associations.each_with_object(properties) do |(name, association), props|
+                if association.polymorphic?
+                  key = association.name + "_ref"
+                  props[key] = {
+                    type: 'object',
+                    description: association_description(key, name),
+                    properties: {
+                      key: type_and_format(:string),
+                      id: type_and_format(:string)
+                    }
+                  }
+                  next
+                end
 
-            def format_field_leaf(field)
-              field_data = type_and_format(field.type, field.options[:item_type])
+                key = association_key(association)
+                description = association_description(key, association.name)
+                formatted_type = if association.type == :has_many
+                  type_and_format(:array, :string)
+                else
+                  type_and_format(:string)
+                end.merge(description: description)
 
-              unless field_data
-                raise "Unknown Brainstem Field type encountered(#{field.type}) for field #{field.name}"
+                props[key] = formatted_type unless props[key]
               end
-
-              field_data.merge!(description: format_description_for(field))
-              field_data.delete(:description) if field_data[:description].blank?
-
-              field_data
             end
 
-            def format_description_for(field)
-              field_description = format_description(field.description) || ''
-              field_description << format_conditional_description(field.options)
-              field_description << "\nOnly returned when requested through the optional_fields param.\n" if field.optional?
-              field_description.try(:chomp!)
-              field_description
+            def association_description(key, name)
+              ["`#{key}` will only be included in the response if `#{name}` is in the list of included associations.",
+                "See <a href='#section/Includes'>include</a> section for usage."].join(' ')
             end
 
-            def format_conditional_description(field_options)
-              return '' if field_options[:if].blank?
-
-              conditions = field_options[:if]
-                .reject { |cond| presenter.conditionals[cond].options[:nodoc] }
-                .map    { |cond| uncapitalize(presenter.conditionals[cond].description) }
-                .delete_if(&:empty?)
-                .uniq
-                .to_sentence
+            def association_key(association)
+              if association.response_key
+                association.response_key
+              else
+                key = association.name.singularize
+                association.type == :has_many ? "#{key}_ids" : "#{key}_id"
+              end
+            end
 
-              conditions.present? ? "\nVisible when #{conditions}.\n" : ''
+            def format_field(field)
+              Brainstem::ApiDocs::FORMATTERS[:presenter_field][:oas_v2].call(presenter, field)
             end
           end
         end