brainstem 1.4.1 → 2.0.0

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

@@ -0,0 +1,99 @@
+require 'brainstem/api_docs/formatters/abstract_formatter'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          class SecurityDefinitionsFormatter < AbstractFormatter
+
+            attr_accessor :output
+
+            def initialize(options = {})
+              self.output = ActiveSupport::HashWithIndifferentAccess.new
+
+              super options
+            end
+
+            def call
+              format_basic_auth_definitions!
+              format_apikey_auth_definitions!
+              format_oauth_definitions!
+              format_security_object!
+
+              output
+            end
+
+            #####################################################################
+            private
+            #####################################################################
+
+            def format_basic_auth_definitions!
+              add_security_definition(basic_auth_definitions)
+            end
+
+            def format_apikey_auth_definitions!
+              add_security_definition(apikey_auth_definitions)
+            end
+
+            def format_oauth_definitions!
+              add_security_definition(oauth_definitions)
+            end
+
+            def format_security_object!
+              return if security_object.blank?
+
+              output.merge!('security' => security_object)
+            end
+
+            def add_security_definition(security_definition)
+              return if security_definition.blank?
+
+              output['securityDefinitions'] ||= {}
+              output['securityDefinitions'].merge!(security_definition)
+            end
+
+            #####################################################################
+            # Override with custom values                                       #
+            #####################################################################
+
+            def basic_auth_definitions
+              {}
+            end
+
+            def apikey_auth_definitions
+              {
+                'api_key' => {
+                  'type' => 'apiKey',
+                  'name' => 'api_key',
+                  'in'   => 'header'
+                }
+              }
+            end
+
+            def oauth_definitions
+              {
+                'petstore_auth' => {
+                  'type'             => 'oauth2',
+                  'authorizationUrl' => 'http://petstore.swagger.io/oauth/dialog',
+                  'flow'             => 'implicit',
+                  'scopes'           => {
+                    'write:pets' => 'modify pets in your account',
+                    'read:pets'  => 'read your pets'
+                  }
+                }
+              }
+            end
+
+            def security_object
+              {}
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:security][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::SecurityDefinitionsFormatter.method(:call)

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

@@ -0,0 +1,123 @@
+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
+          class TagsFormatter < AbstractFormatter
+            include Helper
+
+            #
+            # Declares the options that are permissable to set on this instance.
+            #
+            def valid_options
+              super | [
+                :controllers,
+                :ignore_tagging
+              ]
+            end
+
+            attr_accessor :output,
+                          :controllers,
+                          :ignore_tagging
+
+            def initialize(controllers, options = {})
+              self.output         = ActiveSupport::HashWithIndifferentAccess.new
+              self.controllers    = controllers
+              self.ignore_tagging = false
+
+              super options
+            end
+
+            def call
+              return {} if ignore_tagging || controllers.blank?
+
+              format_tags!
+              format_tag_groups!
+              output
+            end
+
+            #####################################################################
+            private
+            #####################################################################
+
+            def format_tags!
+              output.merge!( 'tags' => format_tags_data )
+            end
+
+            def format_tag_groups!
+              return unless tag_groups_specified?(documentable_controllers)
+
+              output.merge!( 'x-tagGroups' => format_tag_groups )
+            end
+
+            #####################################################################
+            # Override                                                          #
+            #####################################################################
+
+            def documentable_controllers
+              @documentable_controllers ||= controllers.
+                select { |controller| !controller.nodoc? && controller.endpoints.only_documentable.any? }
+            end
+
+            def format_tags_data
+              documentable_controllers
+                .map { |controller| format_tag_data(controller) }
+                .sort_by { |tag_data| tag_data[:name] }
+            end
+
+            def tag_groups_specified?(controllers)
+              documentable_controllers.any? { |controller|
+                controller.tag_groups.present?
+              }
+            end
+
+            def format_tag_groups
+              groups = Hash.new.tap do |result|
+                documentable_controllers.each do |controller|
+                  controller_tag = tag_name(controller)
+                  controller_tag_groups = tag_groups(controller).presence || [controller_tag]
+
+                  controller_tag_groups.each do |tag_group_name|
+                    result[tag_group_name] ||= []
+                    result[tag_group_name] << controller_tag
+                  end
+                end
+              end
+
+              groups.keys.sort.map do |tag_group_name|
+                {
+                  name: tag_group_name,
+                  tags: groups[tag_group_name].sort
+                }.with_indifferent_access
+              end
+            end
+
+            def tag_name(controller)
+              controller.tag.presence || format_tag_name(controller.name)
+            end
+
+            def tag_groups(controller)
+              controller.tag_groups.presence
+            end
+
+            #
+            # Returns formatted tag object for a given controller.
+            #
+            def format_tag_data(controller)
+              {
+                name:        tag_name(controller),
+                description: format_description(controller.description),
+              }.reject { |_, v| v.blank? }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:tags][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::TagsFormatter.method(:call)

data/lib/brainstem/api_docs/introspectors/abstract_introspector.rb

@@ -19,7 +19,6 @@ module Brainstem
           new(options).tap(&:load_environment!)
         end
 
-
         # Override to return a collection of all controller classes.
         #
         # @return [Array<Class>] all controller classes to document
@@ -27,7 +26,6 @@ module Brainstem
           raise NotImplementedError
         end
 
-
         # Override to return a collection of all presenter classes.
         #
         # @return [Array<Class>] all presenter classes to document
@@ -35,7 +33,6 @@ module Brainstem
           raise NotImplementedError
         end
 
-
         # Override to return a collection of hashes with the minimum following
         # keys:
         #
@@ -48,7 +45,6 @@ module Brainstem
           raise NotImplementedError
         end
 
-
         # Provides both a sanity check to ensure that output confirms to
         # interface and also confirms that there is actually something to
         # generate docs for.
@@ -58,7 +54,6 @@ module Brainstem
           valid_controllers? && valid_presenters? && valid_routes?
         end
 
-
         #######################################################################
         private
         #######################################################################
@@ -67,14 +62,12 @@ module Brainstem
         # instantiation happens through +with_loaded_environment.
         private_class_method :new
 
-
         # Loads the host application environment.
         # @api private
         def load_environment!
           raise NotImplementedError
         end
 
-
         def valid_controllers?
           controllers.is_a?(Array) &&
             controllers.count > 0 &&

data/lib/brainstem/api_docs/introspectors/rails_introspector.rb

@@ -24,7 +24,6 @@ module Brainstem
             "You may have to manually specify an Introspector (#{e.message})."
         end
 
-
         #
         # Returns a list of presenters that descend from the base presenter
         # class.
@@ -35,7 +34,6 @@ module Brainstem
           base_presenter_class.constantize.descendants
         end
 
-
         #
         # Returns a list of controllers that descend from the base controller
         # class.
@@ -46,7 +44,6 @@ module Brainstem
           base_controller_class.constantize.descendants
         end
 
-
         #
         # Returns the alternate application class or defaults to Rails.application
         #
@@ -56,7 +53,6 @@ module Brainstem
           base_application_class.present? ? base_application_class.constantize : ::Rails.application
         end
 
-
         #
         # Returns an array of hashes describing the endpoints of the
         # application. See +routes_method+ for the keys of those hashes.
@@ -68,12 +64,10 @@ module Brainstem
           routes_method.call
         end
 
-
         #######################################################################
         private
         #######################################################################
 
-
         def valid_options
           super | [
             :routes_method,
@@ -84,7 +78,6 @@ module Brainstem
           ]
         end
 
-
         #
         # Used to short-circuit loading if Rails is already loaded, which
         # reduces start-up time substantially.
@@ -94,7 +87,6 @@ module Brainstem
           defined? Rails
         end
 
-
         # Returns the path of the Rails +config/environment.rb+ file - by
         # default, +#{Dir.pwd}/config/environment.rb+.
         #
@@ -106,7 +98,6 @@ module Brainstem
           )
         end
 
-
         #
         # Allows a custom location to be set for the environment file if - for
         # example - the command were to be called from a cron task that cannot
@@ -114,7 +105,6 @@ module Brainstem
         #
         attr_writer :rails_environment_file
 
-
         #
         # Returns the name of the base presenter class.
         #
@@ -130,7 +120,6 @@ module Brainstem
           proc_or_string.respond_to?(:call) ? proc_or_string.call : proc_or_string
         end
 
-
         #
         # Allows for the specification for an alternate base presenter class
         # if - for example - only documentation of children of +MyBasePresenter+
@@ -149,7 +138,6 @@ module Brainstem
         #
         attr_writer :base_presenter_class
 
-
         #
         # Returns the name of the base controller class.
         #
@@ -165,7 +153,6 @@ module Brainstem
           proc_or_string.respond_to?(:call) ? proc_or_string.call : proc_or_string
         end
 
-
         #
         # Allows for the specification for an alternate base controller class
         # if - for example - only documentation of children of ApiController
@@ -185,7 +172,6 @@ module Brainstem
         #
         attr_writer :base_controller_class
 
-
         #
         # Returns the name of the alternate application or engine to get routes from.
         #
@@ -200,7 +186,6 @@ module Brainstem
           proc_or_string.respond_to?(:call) ? proc_or_string.call : proc_or_string
         end
 
-
         #
         # Allows for the specification for an alternate base application name
         #
@@ -208,7 +193,6 @@ module Brainstem
         #
         attr_writer :base_application_class
 
-
         #
         # Returns the proc that is called to format and retrieve routes.
         # The proc's return must be an array of hashes that contains the
@@ -244,7 +228,6 @@ module Brainstem
           end
         end
 
-
         #
         # Allows setting the routes method used to retrieve the routes if - for
         # example - your application needs to retrieve additional data or if it
@@ -252,13 +235,11 @@ module Brainstem
         #
         attr_writer :routes_method
 
-
         #
         # Throws an error if the introspector did not produce valid results.
         #
         def validate!
-          raise InvalidIntrospectorError, "Introspector is not valid." \
-            unless valid?
+          raise InvalidIntrospectorError, "Introspector is not valid." unless valid?
         end
       end
     end

data/lib/brainstem/api_docs/presenter.rb

@@ -14,7 +14,6 @@ module Brainstem
       include Concerns::Optional
       include Concerns::Formattable
 
-
       def valid_options
         super | [
           :const,
@@ -37,7 +36,6 @@ module Brainstem
       alias_method :document_empty_associations?, :document_empty_associations
       alias_method :document_empty_filters?,      :document_empty_filters
 
-
       def initialize(atlas, options = {})
         self.atlas = atlas
         self.document_empty_associations = Brainstem::ApiDocs.document_empty_presenter_associations
@@ -47,63 +45,51 @@ module Brainstem
         yield self if block_given?
       end
 
-
       def suggested_filename(format)
         filename_pattern
           .gsub('{{name}}', target_class.to_s.underscore)
           .gsub('{{extension}}', extension)
       end
 
-
       def suggested_filename_link(format)
         filename_link_pattern
           .gsub('{{name}}', target_class.to_s.underscore)
           .gsub('{{extension}}', extension)
       end
 
-
       attr_accessor :atlas
 
-
       def extension
         @extension ||= Brainstem::ApiDocs.output_extension
       end
 
-
       def filename_pattern
         @filename_pattern ||= Brainstem::ApiDocs.presenter_filename_pattern
       end
 
-
       def filename_link_pattern
         @filename_link_pattern ||= Brainstem::ApiDocs.presenter_filename_link_pattern
       end
 
-
       delegate :configuration => :const
       delegate :find_by_class => :atlas
 
-
       def nodoc?
         configuration[:nodoc]
       end
 
-
       def title
         contextual_documentation(:title) || const.to_s.demodulize
       end
 
-
       def brainstem_keys
         const.possible_brainstem_keys.to_a.sort
       end
 
-
       def description
         contextual_documentation(:description) || ""
       end
 
-
       def valid_fields(fields = configuration[:fields])
         fields.to_h.reject do |_, field|
           invalid_field?(field) || (nested_field?(field) && valid_fields_in(field).none?)
@@ -111,16 +97,32 @@ module Brainstem
       end
       alias_method :valid_fields_in, :valid_fields
 
-
       def invalid_field?(field)
         field.options[:nodoc]
       end
 
-
       def nested_field?(field)
         field.respond_to?(:configuration)
       end
 
+      def optional_field?(field)
+        field.options[:optional]
+      end
+
+      def optional_field_names(fields = configuration[:fields], buffer = [])
+        fields.to_h.each do |field_name, field_config|
+          next if invalid_field?(field_config)
+
+          if optional_field?(field_config)
+            buffer << field_name
+          elsif nested_field?(field_config)
+            optional_field_names_in(field_config.configuration, buffer)
+          end
+        end
+
+        buffer
+      end
+      alias_method :optional_field_names_in, :optional_field_names
 
       def valid_filters
         configuration[:filters]
@@ -128,7 +130,6 @@ module Brainstem
           .keep_if(&method(:documentable_filter?))
       end
 
-
       def documentable_filter?(_, filter)
         !filter[:nodoc] &&
           (
@@ -137,20 +138,20 @@ module Brainstem
           )
       end
 
+      def searchable?
+        configuration[:search].present?
+      end
 
       def valid_sort_orders
         configuration[:sort_orders].to_h.reject {|k, v| v[:nodoc] }
       end
 
-
       def valid_associations
         configuration[:associations]
           .to_h
           .keep_if(&method(:documentable_association?))
       end
 
-
-
       def link_for_association(association)
         if (associated_presenter = find_by_class(association.target_class)) &&
             !associated_presenter.nodoc?
@@ -160,7 +161,6 @@ module Brainstem
         end
       end
 
-
       #
       # Returns whether this association should be documented based on nodoc
       # and empty description.
@@ -175,27 +175,22 @@ module Brainstem
           )
       end
 
-
       def conditionals
         configuration[:conditionals]
       end
 
-
       def default_sort_order
         configuration[:default_sort_order] || ""
       end
 
-
       def default_sort_field
         @default_sort_field ||= (default_sort_order.split(":")[0] || nil)
       end
 
-
       def default_sort_direction
         @default_sort_direction ||= (default_sort_order.split(":")[1] || nil)
       end
 
-
       #
       # Returns a key if it exists and is documentable.
       #
@@ -205,7 +200,6 @@ module Brainstem
           configuration[key][:info]
       end
 
-
       #
       # Returns the relative path between this presenter and another given
       # presenter.