brainstem 1.4.1 → 2.0.0

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

@@ -0,0 +1,66 @@
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Helper
+          def presenter_title(presenter)
+            presenter.contextual_documentation(:title).presence ||
+                presenter.target_class.underscore.singularize.titleize.strip
+          end
+
+          def format_http_method(endpoint)
+            endpoint.http_methods.first.downcase
+          end
+
+          def format_tag_name(name)
+            return name if name.blank?
+
+            name.underscore.titleize.strip
+          end
+
+          def format_description(description)
+            return '' if description.blank?
+
+            desc = description.to_s.strip.tap { |desc| desc[0] = desc[0].upcase }
+            desc += "." unless desc =~ /\.\s*\z/
+            desc
+          end
+
+          def uncapitalize(description)
+            return '' if description.blank?
+
+            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' } }
+              else
+                TYPE_INFO[type.to_s]
+            end
+            result ? result.with_indifferent_access : nil
+          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'     },
+          }
+          private_constant :TYPE_INFO
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+require 'brainstem/api_docs/formatters/abstract_formatter'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          class ControllerFormatter < AbstractFormatter
+
+            #
+            # Declares the options that are permissable to set on this instance.
+            #
+            def valid_options
+              super | [
+                :include_actions
+              ]
+            end
+
+            attr_accessor :controller,
+                          :include_actions,
+                          :output
+
+            alias_method :include_actions?,
+                         :include_actions
+
+            def initialize(controller, options = {})
+              self.controller      = controller
+              self.output          = {}
+              self.include_actions = true
+
+              super options
+            end
+
+            def call
+              return {} if controller.nodoc?
+
+              format_actions!
+            end
+
+            #####################################################################
+            private
+            #####################################################################
+
+            def format_actions!
+              return unless include_actions?
+
+              controller.valid_sorted_endpoints.formatted_as(:oas_v2)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:controller][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::ControllerFormatter.method(:call)

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

@@ -0,0 +1,311 @@
+require 'active_support/core_ext/hash/except'
+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/markdown/helper'
+
+#
+# Responsible for formatting each endpoint.
+#
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          module Endpoint
+            class ParamDefinitionsFormatter < AbstractFormatter
+              include Helper
+              include ::Brainstem::ApiDocs::Formatters::Markdown::Helper
+
+              attr_reader :output
+
+              def initialize(endpoint)
+                @endpoint    = endpoint
+                @http_method = format_http_method(endpoint)
+                @presenter   = endpoint.presenter
+                @output      = []
+              end
+
+              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 http_method != 'delete'
+                  format_optional_params!
+                  format_include_params!
+                end
+
+                format_query_params!
+                format_body_params!
+
+                output
+              end
+
+              ################################################################################
+              private
+              ################################################################################
+
+              attr_reader :endpoint, :presenter, :http_method
+
+              def format_path_params!
+                path_params.each do |param|
+                  model_name = param.match(/_id/) ? param.split('_id').first : 'model'
+
+                  output << {
+                    'in'          => 'path',
+                    'name'        => param,
+                    'required'    => true,
+                    'type'        => 'integer',
+                    'description' => "The ID of the #{model_name.humanize}."
+                  }
+                end
+              end
+
+              def path_params
+                endpoint.path
+                  .gsub('(.:format)', '')
+                  .scan(/(:(?<param>\w+))/)
+                  .flatten
+              end
+
+              def nested_properties(param_config)
+                param_config.except(:_config)
+              end
+
+              def format_pagination_params!
+                output << format_query_param(:page, type: 'integer', default: 1)
+                output << format_query_param(:per_page, type: 'integer', default: 20, maximum: 200)
+              end
+
+              def format_search_param!
+                return if presenter.nil? || !presenter.searchable?
+
+                output << format_query_param(:search, type: 'string')
+              end
+
+              def format_only_param!
+                output << format_query_param(:only,
+                  type: 'string',
+                  info: <<-DESC.strip_heredoc
+                    Allows you to request one or more resources directly by ID. Multiple IDs can be supplied
+                    in a comma separated list, like `GET /api/v1/workspaces.json?only=5,6,7`.
+                  DESC
+                )
+              end
+
+              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")]
+                }.flatten.sort
+
+                description = <<-DESC.strip_heredoc
+                  Supply `order` with the name of a valid sort field for the endpoint and a direction.
+
+                  Valid values: #{sort_orders.to_sentence}.
+                DESC
+
+                output << format_query_param('order',
+                  info:    description,
+                  type:    'string',
+                  default: presenter.default_sort_order
+                )
+              end
+
+              def format_filter_params!
+                return if presenter.nil?
+
+                presenter.valid_filters.each do |filter_name, filter_config|
+                  output << format_query_param(filter_name, filter_config)
+                end
+              end
+
+              def format_optional_params!
+                return if presenter.nil? || (optional_field_names = presenter.optional_field_names).empty?
+
+                output << format_query_param('optional_fields',
+                  info:      'Allows you to request one or more optional fields as an array',
+                  type:      'array',
+                  item_type: 'string',
+                  items:     optional_field_names
+                )
+              end
+
+              def format_include_params!
+                return if presenter.nil? || presenter.valid_associations.empty?
+
+                output << format_query_param('include',
+                  type: 'string',
+                  info: include_params_description
+                )
+              end
+
+              def include_params_description
+                result = "Any of the below associations can be included in your request by providing the `include` "\
+                         "param, e.g. `include=association1,association2`.\n"
+
+                presenter.valid_associations
+                  .sort_by { |_, association| association.name }
+                  .each do |_, association|
+
+                  text = md_inline_code(association.name)
+                  text += " (#{ association.target_class.to_s })"
+
+                  desc = format_description(association.description)
+                  if association.options && association.options[:restrict_to_only]
+                    desc += "  Restricted to queries using the #{md_inline_code("only")} parameter."
+                  end
+
+                  result << md_li(text + (desc.present? ? " - #{desc}" : ''))
+                end
+
+                result
+              end
+
+              def format_query_params!
+                endpoint.params_configuration_tree.each do |param_name, param_config|
+                  next if nested_properties(param_config).present?
+
+                  output << format_query_param(param_name, param_config[:_config])
+                end
+
+                # Sort all query params by required attribute & alphabetically.
+                output.sort_by! { |param| [(param['required'] ? 0 : 1), param['name']] }
+              end
+
+              def format_query_param(param_name, param_config)
+                type_data = type_and_format(param_config[:type], param_config[:item_type])
+                if type_data.nil?
+                  raise "Unknown Brainstem Param type encountered(#{param_config[:type]}) for param #{param_name}"
+                end
+
+                if param_config[:type].to_s == 'array'
+                  type_data[:items].merge!(
+                    {
+                      'type'    => param_config[:item_type],
+                      'enum'    => param_config[:items],
+                      'default' => param_config[:default],
+                    }.compact
+                  )
+                else
+                  type_data.merge!(
+                    'default'     => param_config[:default],
+                    'minimum'     => param_config[:minimum],
+                    'maximum'     => param_config[:maximum]
+                  )
+                end
+
+                {
+                  'in'          => 'query',
+                  'name'        => param_name.to_s,
+                  'required'    => param_config[:required],
+                  'description' => format_description(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?
+
+                output << {
+                  'in'          => 'body',
+                  'required'    => true,
+                  'name'        => 'body',
+                  'schema'      => {
+                    'type'       => 'object',
+                    'properties' => formatted_body_params
+                  },
+                }
+              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))
+                      }
+                    }
+                  else
+                    raise "Unknown Brainstem body param encountered(#{param_config[:type]}) for field #{param_name}"
+                end
+
+                result.with_indifferent_access.reject { |_, v| v.blank? }
+              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
+                  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
+                  end
+
+                  buffer[param_name.to_s] = {
+                    title:       param_name.to_s,
+                    description: format_description(param_config[:info])
+                  }.merge(branch_schema).reject { |_, v| v.blank? }
+
+                  buffer
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:parameters][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::Endpoint::ParamDefinitionsFormatter.method(:call)

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

@@ -0,0 +1,197 @@
+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 'forwardable'
+
+#
+# Responsible for formatting a response for an endpoint.
+#
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          module Endpoint
+            class ResponseDefinitionsFormatter < AbstractFormatter
+              include Helper
+
+              attr_reader :output
+
+              def initialize(endpoint)
+                @endpoint    = endpoint
+                @http_method = format_http_method(endpoint)
+                @presenter   = endpoint.presenter
+                @model_name  = presenter ? presenter_title(presenter) : "object"
+                @output      = ActiveSupport::HashWithIndifferentAccess.new
+              end
+
+              def call
+                if endpoint.custom_response_configuration_tree.present?
+                  format_custom_response!
+                elsif http_method == 'delete'
+                  format_delete_response!
+                else
+                  format_schema_response!
+                end
+                format_error_responses!
+
+                output
+              end
+
+              ################################################################################
+              private
+              ################################################################################
+
+              attr_reader :endpoint,
+                          :presenter,
+                          :model_name,
+                          :http_method
+
+              def format_delete_response!
+                output.merge! '204' => { description: success_response_description }
+              end
+
+              def nested_properties(param_config)
+                param_config.except(:_config)
+              end
+
+              def success_response_description
+                case http_method
+                  when 'post'
+                    "#{model_name} has been created."
+                  when 'put', 'patch'
+                    "#{model_name} has been updated."
+                  when 'delete'
+                    "#{model_name} has been deleted."
+                  else
+                    "A list of #{model_name.pluralize} have been retrieved."
+                end
+              end
+
+              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: {
+                      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}"
+                        }
+                      }
+                    }
+                  }
+                }
+              end
+
+              def format_error_responses!
+                output.merge!(
+                  '400' => { description: 'Bad Request',            schema: { '$ref' => '#/definitions/Errors' }  },
+                  '401' => { description: 'Unauthorized request',   schema: { '$ref' => '#/definitions/Errors' }  },
+                  '403' => { description: 'Forbidden request',      schema: { '$ref' => '#/definitions/Errors' }  },
+                  '404' => { description: 'Page Not Found',         schema: { '$ref' => '#/definitions/Errors' }  },
+                  '503' => { description: 'Service is unavailable', schema: { '$ref' => '#/definitions/Errors' }  }
+                )
+              end
+
+              def format_custom_response!
+                output.merge! '200' => {
+                  description: success_response_description,
+                  schema: format_response(endpoint.custom_response_configuration_tree)
+                }
+              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
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:response][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::Endpoint::ResponseDefinitionsFormatter.method(:call)