brainstem 1.4.1 → 2.0.0

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

@@ -0,0 +1,60 @@
+require 'brainstem/api_docs/formatters/abstract_formatter'
+
+#
+# Responsible for formatting each endpoint.
+#
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          class EndpointCollectionFormatter < AbstractFormatter
+
+            attr_accessor :endpoint_collection,
+                          :output
+
+            def initialize(endpoint_collection, options = {})
+              self.endpoint_collection = endpoint_collection
+              self.output              = {}
+
+              super options
+            end
+
+            def call
+              format_endpoints!
+            end
+
+            #####################################################################
+            private
+            #####################################################################
+
+            def documentable_endpoints
+              endpoint_collection
+                .only_documentable
+            end
+
+            def format_endpoints!
+              documentable_endpoints.each do |endpoint|
+                formatted_endpoint = endpoint.formatted_as(:oas_v2)
+                next if formatted_endpoint.blank?
+
+                if (common_keys = output.keys & formatted_endpoint.keys).present?
+                  common_keys.each do |key|
+                    output[key].merge!(formatted_endpoint[key])
+                  end
+                else
+                  output.merge!(formatted_endpoint)
+                end
+              end
+
+              output
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:endpoint_collection][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::EndpointCollectionFormatter.method(:call)

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

@@ -0,0 +1,162 @@
+require 'active_support/core_ext/hash/except'
+require 'forwardable'
+require 'brainstem/api_docs/formatters/abstract_formatter'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/endpoint/param_definitions_formatter'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/endpoint/response_definitions_formatter'
+require 'brainstem/api_docs/formatters/open_api_specification/helper'
+
+#
+# Responsible for formatting each endpoint.
+#
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          class EndpointFormatter < AbstractFormatter
+            include Helper
+            extend Forwardable
+
+            attr_accessor :endpoint,
+                          :presenter,
+                          :endpoint_key,
+                          :http_method,
+                          :output
+
+            def initialize(endpoint, options = {})
+              self.endpoint     = endpoint
+              self.presenter    = endpoint.presenter
+              self.endpoint_key = formatted_url
+              self.http_method  = format_http_method(endpoint)
+              self.output       = { endpoint_key => { http_method => {} } }.with_indifferent_access
+
+              super options
+            end
+
+            def call
+              return {} if endpoint.nodoc?
+
+              format_summary!
+              format_optional_info!
+              format_security!
+              format_tags!
+              format_parameters!
+              format_response!
+
+              output
+            end
+
+            ################################################################################
+            private
+            ################################################################################
+
+            delegate :controller => :endpoint
+
+            ################################################################################
+            # Methods to override
+            ################################################################################
+
+            #
+            # Format the endpoint summary
+            #
+            def summary
+              endpoint.title
+            end
+
+            #
+            # Format the endpoint description
+            #
+            def description
+              endpoint.description
+            end
+
+            #
+            # Formats the actual URI
+            #
+            def formatted_url
+              endpoint.path
+                .gsub('(.:format)', '')
+                .gsub(/(:(?<param>\w+))/, '{\k<param>}')
+                .gsub(Brainstem::ApiDocs.base_path, '')
+            end
+
+            ################################################################################
+            # Avoid overridding
+            ################################################################################
+
+            #
+            # Formats the summary as given, falling back to the humanized action
+            # name.
+            #
+            def format_summary!
+              output[endpoint_key][http_method].merge! summary: summary.to_s.strip
+            end
+
+            #
+            # Adds the following properties.
+            #   - description
+            #   - operation_id
+            #   - consumes
+            #   - produces
+            #   - schemes
+            #   - external_docs
+            #   - deprecated
+            #
+            def format_optional_info!
+              info = {
+                description:    format_description(description),
+                operation_id:   endpoint.operation_id,
+                consumes:       endpoint.consumes,
+                produces:       endpoint.produces,
+                schemes:        endpoint.schemes,
+                external_docs:  endpoint.external_docs,
+                deprecated:     endpoint.deprecated,
+              }.reject { |_,v| v.blank? }
+
+              output[endpoint_key][http_method].merge!(info)
+            end
+
+            #
+            # Adds the security schemes for the given endpoint.
+            #
+            def format_security!
+              return if endpoint.security.nil?
+
+              output[endpoint_key][http_method].merge! security: endpoint.security
+            end
+
+            #
+            # Adds the tags for the given endpoint.
+            #
+            def format_tags!
+              tag_name = endpoint.controller.tag || format_tag_name(endpoint.controller.name)
+
+              output[endpoint_key][http_method].merge! tags: [tag_name]
+            end
+
+            #
+            # Formats each parameter.
+            #
+            def format_parameters!
+              output[endpoint_key][http_method].merge!(
+                parameters: ::Brainstem::ApiDocs::FORMATTERS[:parameters][:oas_v2].call(endpoint)
+              )
+            end
+
+            #
+            # Formats the response.
+            #
+            def format_response!
+              output[endpoint_key][http_method].merge!(
+                responses: ::Brainstem::ApiDocs::FORMATTERS[:response][:oas_v2].call(endpoint)
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:endpoint][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::EndpointFormatter.method(:call)

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

@@ -0,0 +1,126 @@
+require 'brainstem/api_docs/formatters/abstract_formatter'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          class InfoFormatter < AbstractFormatter
+
+            #
+            # Declares the options that are permissable to set on this instance.
+            #
+            def valid_options
+              super | [
+                :version
+              ]
+            end
+
+            attr_accessor :output,
+                          :version
+
+            def initialize(options = {})
+              self.output = ActiveSupport::HashWithIndifferentAccess.new
+
+              super options
+            end
+
+            def call
+              format_swagger_object!
+              format_info_object!
+              output
+            end
+
+            #####################################################################
+            private
+            #####################################################################
+
+            def format_swagger_object!
+              output.merge!( swagger_object )
+            end
+
+            def format_info_object!
+              output.merge!( 'info' => info_object )
+            end
+
+            def swagger_object
+              {
+                'swagger'  => '2.0',
+                'host'     => host,
+                'basePath' => Brainstem::ApiDocs.base_path,
+                'schemes'  => schemes,
+                'consumes' => consumes,
+                'produces' => produces
+              }.with_indifferent_access.reject { |_, v| v.blank? }
+            end
+
+            def info_object
+              {
+                'version'        => version.presence || '1.0',
+                'title'          => title,
+                'description'    => description,
+                'termsOfService' => terms_of_service,
+                'contact'        => contact_object,
+                'license'        => license_object
+              }.with_indifferent_access.reject { |_, v| v.blank? }
+            end
+
+            #####################################################################
+            # Override with custom values                                       #
+            #####################################################################
+
+            def host
+              'petstore.swagger.io'
+            end
+
+            def schemes
+              %w(https)
+            end
+
+            def consumes
+              %w(application/json)
+            end
+
+            def produces
+              %w(application/json)
+            end
+
+            def title
+              'Petstore'
+            end
+
+            def description
+              <<-DESC.strip_heredoc
+                This is a sample server Petstore server. You can find out more about Swagger at
+                [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).
+                For this sample, you can use the api key `special-key` to test the authorization filters.
+              DESC
+            end
+
+            def terms_of_service
+              'http://swagger.io/terms/'
+            end
+
+            def contact_object
+              {
+                'name'  => 'Pet Store Support',
+                'url'   => 'https://swagger.io/support/',
+                'email' => 'apiteam@swagger.io',
+              }
+            end
+
+            def license_object
+              {
+                'name' => 'MIT',
+                'url'  => 'https://opensource.org/licenses/MIT',
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:info][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::InfoFormatter.method(:call)

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

@@ -0,0 +1,132 @@
+require 'active_support/core_ext/string/inflections'
+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 PresenterFormatter < AbstractFormatter
+            include Helper
+
+            def initialize(presenter, options = {})
+              self.presenter  = presenter
+              self.definition = ActiveSupport::HashWithIndifferentAccess.new
+              self.output     = ActiveSupport::HashWithIndifferentAccess.new
+
+              super options
+            end
+
+            attr_accessor :presenter,
+                          :output,
+                          :definition,
+                          :presented_class
+
+            def call
+              return {} if presenter.nodoc?
+
+              format_title!
+              format_description!
+              format_type!
+              format_fields!
+
+              output.merge!(presenter.target_class => definition.reject {|_, v| v.blank?})
+            end
+
+            #####################################################################
+            private
+            #####################################################################
+
+            def format_title!
+              definition.merge! title: presenter_title(presenter)
+            end
+
+            def format_description!
+              definition.merge! description: format_description(presenter.description)
+            end
+
+            def format_type!
+              definition.merge! type: 'object'
+            end
+
+            def format_fields!
+              return unless presenter.valid_fields.any?
+
+              definition.merge! properties: format_field_branch(presenter.valid_fields)
+            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
+              end
+            end
+
+            def nested_field?(field)
+              field.respond_to?(:configuration)
+            end
+
+            def format_field_leaf(field)
+              field_data = type_and_format(field.type, field.options[:item_type])
+
+              unless field_data
+                raise "Unknown Brainstem Field type encountered(#{field.type}) for field #{field.name}"
+              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
+            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
+
+Brainstem::ApiDocs::FORMATTERS[:presenter][:oas_v2] =
+  Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::PresenterFormatter.method(:call)