grape_ape_rails 0.5.0

data/lib/grape_ape_rails/handlers/header_versioning.rb

@@ -0,0 +1,27 @@
+module GrapeApeRails
+  module Handlers
+    module HeaderVersioning
+      extend ActiveSupport::Concern
+
+      included do
+        gar_resource = self.name.split('::').last.underscore
+        gar_version = self.name.split('::')[-2].underscore.gsub('_','.')
+        cascades = GrapeApeRails::API.api_version_cascades_map
+        gar_version = cascades[gar_version] if cascades[gar_version].present?
+        gar_appname = GrapeApeRails.configuration.app_name
+        gar_organization = GrapeApeRails.configuration.organization_name
+        version gar_version, using: :header, vendor: "#{gar_organization}.#{gar_appname}", strict: true
+
+        before do
+          req = Rack::Request.new(env)
+          api_key = version ? GrapeApeRails::API.api_keys_map[version] : nil
+          if api_key.nil?
+            msg = "Cannot determine API version from header info."
+            error!({ code: "UNAUTHORIZED", message: msg}, 401)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/grape_ape_rails/handlers/locale.rb

@@ -0,0 +1,24 @@
+module GrapeApeRails
+  module Handlers
+    module Locale
+
+      extend ActiveSupport::Concern
+
+      included do
+        I18n.config.enforce_available_locales = true
+        I18n.config.load_path += Dir['./config/locales/*.yml']
+        I18n.config.available_locales = GrapeApeRails.configuration.available_locales
+        I18n.config.default_locale = :en
+
+        before do
+          # set the locale based on Accept-Language or params[:locale]
+          req = Rack::Request.new(env)
+          params_locale = (req.params['locale'] && I18n.available_locales.include?(req.params['locale'].downcase.to_sym)) ? req.params['locale'] : nil
+          I18n.locale = env.http_accept_language.compatible_language_from(I18n.available_locales) || params_locale || :en
+        end
+      end
+
+    end
+  end
+end
+

data/lib/grape_ape_rails/handlers/rails_logging.rb

@@ -0,0 +1,33 @@
+module GrapeApeRails
+  module Handlers
+    class RailsLogging
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        api_version = env['rack.routing_args'][:route_info].route_version rescue nil
+        payload = {
+          remote_addr:    env['REMOTE_ADDR'],
+          request_method: env['REQUEST_METHOD'],
+          request_path:   env['PATH_INFO'],
+          request_query:  env['QUERY_STRING'],
+          api_version:    api_version
+        }
+        req = Rack::Request.new(env)
+        payload[:params] = req.params
+        ActiveSupport::Notifications.instrument "grape.request", payload do
+          @app.call(env).tap do |response|
+            status, headers, body = *response
+            payload[:params].merge!(env["api.endpoint"].params.to_hash)
+            payload[:params].delete("route_info")
+            payload[:params].delete("format")
+            payload[:response_status] = status
+          end
+        end
+      rescue
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/grape_ape_rails/handlers/responses.rb

@@ -0,0 +1,32 @@
+module GrapeApeRails
+  module Handlers
+    module Responses
+      extend ActiveSupport::Concern
+
+      included do
+        format :json
+        formatter :json, Grape::Formatter::GarRabl
+        error_formatter :json, Grape::Formatter::GarError
+
+        before do
+          # ...
+        end
+
+        rescue_from Grape::Exceptions::ValidationErrors do |e|
+          status = 422
+          hash_err = { error: {
+            code: 'RESOURCE_FAILED_VALIDATION',
+            message: '[RESOURCE_FAILED_VALIDATION] Resource failed validation per API parameter requirements' }
+          }
+          log_msg = hash_err[:error].clone
+          hash_err[:error].merge!({ data: e.errors }) if e.errors.present?
+          if defined?(::Rails) && Rails.respond_to?(:logger)
+            api_version = "[#{env['rack.routing_args'][:route_info].route_version}]" rescue nil
+            Rails.logger.warn "[API]#{api_version} Responding with #{status} #{log_msg}"
+          end
+          Rack::Response.new(MultiJson.dump(hash_err), status)
+        end
+      end
+    end
+  end
+end

data/lib/grape_ape_rails/handlers.rb

@@ -0,0 +1,22 @@
+module GrapeApeRails
+  module Handlers
+    module All
+      extend ActiveSupport::Concern
+
+      included do
+        # middleware for every API
+        use ::HttpAcceptLanguage::Middleware
+        use ::GrapeApeRails::Handlers::RailsLogging
+
+        # third-party Grape tools
+        include Grape::Kaminari
+        include Grape::Rails::Cache
+
+        # Gar-specific handlers
+        include GrapeApeRails::Handlers::HeaderVersioning
+        include GrapeApeRails::Handlers::Responses
+        include GrapeApeRails::Handlers::Locale
+      end
+    end
+  end
+end

data/lib/grape_ape_rails/railtie.rb

@@ -0,0 +1,9 @@
+require 'grape_ape_rails'
+require 'rails'
+module GrapeApeRails
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "tasks/routes.rake"
+    end
+  end
+end

data/lib/grape_ape_rails/version.rb

@@ -0,0 +1,3 @@
+module GrapeApeRails
+  VERSION = "0.5.0"
+end

data/lib/grape_ape_rails.rb

@@ -0,0 +1,55 @@
+require "grape_ape_rails/version"
+
+require 'active_support'
+require 'grape'
+require 'swagger/grape_swagger_modified'
+require 'grape_ape_rails/railtie' if defined?(Rails)
+require 'grape_ape_rails/api'
+require 'grape_ape_rails/base'
+require 'grape_ape_rails/handlers/header_versioning'
+require 'grape_ape_rails/handlers/responses'
+require 'grape_ape_rails/handlers/formatters'
+require 'grape_ape_rails/handlers/locale'
+require 'grape_ape_rails/handlers'
+
+
+module GrapeApeRails
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+    raise_configuration_errors!
+    self
+  end
+
+  def self.raise_configuration_errors!
+    if self.configuration.api_header_security_enabled
+      %i[ app_name organization_name api_secret_key ].each do |setting|
+        if self.configuration.send(setting).nil?
+          raise "You must set #{setting} in a configuration block in your initializer!"
+        end
+      end
+    end
+  end
+
+  class Configuration
+    attr_accessor :app_name, :organization_name,
+                  :api_secret_key, :api_header_security_enabled,
+                  :available_locales, :security_envelope_debug
+
+    def initialize
+      @app_name = nil
+      @organization_name = nil
+      @api_secret_key = nil
+      @api_header_security_enabled = true
+      @api_security_algorithm = "sha256"
+      @available_locales = [ :en ]
+      # ...
+    end
+  end
+
+end

data/lib/swagger/grape_swagger_modified.rb

@@ -0,0 +1,470 @@
+require 'kramdown'
+module Grape
+  class API
+    class << self
+      attr_reader :combined_routes, :combined_namespaces
+
+      def add_swagger_documentation(options = {})
+        documentation_class = create_documentation_class
+        documentation_class.setup({ target_class: self }.merge(options))
+        mount(documentation_class)
+
+        @combined_routes = {}
+        routes.each do |route|
+          route_match = route.route_path.split(route.route_prefix).last.match('\/([\w|-]*?)[\.\/\(]')
+          next if route_match.nil?
+          resource = route_match.captures.first
+          next if resource.empty?
+          resource.downcase!
+          @combined_routes[resource] ||= []
+          next if @@hide_documentation_path && route.route_path.include?(@@mount_path)
+          @combined_routes[resource] << route
+        end
+
+        @combined_namespaces = {}
+        combine_namespaces(self)
+      end
+
+      private
+
+      def combine_namespaces(app)
+        app.endpoints.each do |endpoint|
+          ns = endpoint.settings.stack.last[:namespace]
+          @combined_namespaces[ns.space] = ns if ns
+
+          combine_namespaces(endpoint.options[:app]) if endpoint.options[:app]
+        end
+      end
+
+      def create_documentation_class
+        Class.new(Grape::API) do
+          class << self
+            def name
+              @@class_name
+            end
+          end
+
+          def self.setup(options)
+            defaults = {
+              target_class: nil,
+              mount_path: '/swagger_doc',
+              mount_with_version: false,
+              base_path: nil,
+              api_version: '0.1',
+              markdown: false,
+              hide_documentation_path: false,
+              hide_format: false,
+              format: nil,
+              models: [],
+              info: {},
+              authorizations: nil,
+              root_base_path: true,
+              api_documentation: { desc: 'Swagger compatible API description' },
+              specific_api_documentation: { desc: 'Swagger compatible API description for specific API' }
+            }
+
+            options = defaults.merge(options)
+
+            target_class     = options[:target_class]
+            api_version      = options[:api_version]
+            @@mount_path     = options[:mount_path] + ((options[:mount_with_version] and api_version.present?) ? "/#{api_version}" : '')
+            @@class_name     = options[:class_name] || options[:mount_path].gsub('/', '')
+            @@markdown       = options[:markdown]
+            @@hide_format    = options[:hide_format]
+            base_path        = options[:base_path]
+            authorizations   = options[:authorizations]
+            root_base_path   = options[:root_base_path]
+            extra_info       = options[:info]
+            api_doc          = options[:api_documentation].dup
+            specific_api_doc = options[:specific_api_documentation].dup
+            @@models         = options[:models] || []
+            @@hide_documentation_path = options[:hide_documentation_path]
+
+            if options[:format]
+              [:format, :default_format, :default_error_formatter].each do |method|
+                send(method, options[:format])
+              end
+            end
+
+            desc api_doc.delete(:desc), params: api_doc.delete(:params)
+            @last_description.merge!(api_doc)
+            get @@mount_path do
+              header['Access-Control-Allow-Origin']   = '*'
+              header['Access-Control-Request-Method'] = '*'
+
+              routes = target_class.combined_routes
+              namespaces = target_class.combined_namespaces
+
+              if @@hide_documentation_path
+                routes.reject! { |route, _value| "/#{route}/".index(parse_path(@@mount_path, nil) << '/') == 0 }
+              end
+
+              routes_array = routes.keys.map do |local_route|
+                next if routes[local_route].all?(&:route_hidden)
+
+                url_format  = '.{format}' unless @@hide_format
+
+                description = namespaces[local_route] && namespaces[local_route].options[:desc]
+                description ||= "Operations about #{local_route.pluralize}"
+
+                {
+                  path: "/#{local_route}#{url_format}",
+                  description: description
+                }
+              end.compact
+
+              output = {
+                apiVersion:     api_version,
+                swaggerVersion: '1.2',
+                produces:       content_types_for(target_class),
+                apis:           routes_array,
+                info:           parse_info(extra_info)
+              }
+
+              output[:authorizations] = authorizations unless authorizations.nil? || authorizations.empty?
+
+              output
+            end
+
+            desc specific_api_doc.delete(:desc), params: {
+              'name' => {
+                desc: 'Resource name of mounted API',
+                type: 'string',
+                required: true
+              }
+            }.merge(specific_api_doc.delete(:params) || {})
+            @last_description.merge!(specific_api_doc)
+            get "#{@@mount_path}/:name" do
+              header['Access-Control-Allow-Origin']   = '*'
+              header['Access-Control-Request-Method'] = '*'
+
+              models = []
+              routes = target_class.combined_routes[params[:name]]
+              error!('Not Found', 404) unless routes
+
+              ops = routes.reject(&:route_hidden).group_by do |route|
+                parse_path(route.route_path, api_version)
+              end
+
+              error!('Not Found', 404) unless ops.any?
+
+              apis = []
+
+              ops.each do |path, op_routes|
+                operations = op_routes.map do |route|
+                  notes       = as_markdown(route.route_notes)
+
+                  http_codes  = parse_http_codes(route.route_http_codes, models)
+
+                  models << @@models if @@models.present?
+
+                  models << route.route_entity if route.route_entity.present?
+
+                  models = models_with_included_presenters(models.flatten.compact)
+
+                  operation = {
+                    notes: notes.to_s,
+                    summary: route.route_description || '',
+                    nickname: route.route_nickname || (route.route_method + route.route_path.gsub(/[\/:\(\)\.]/, '-')),
+                    method: route.route_method,
+                    parameters: parse_header_params(route.route_headers) + parse_params(route.route_params, route.route_path, route.route_method),
+                    type: 'void'
+                  }
+                  operation[:authorizations] = route.route_authorizations unless route.route_authorizations.nil? || route.route_authorizations.empty?
+                  if operation[:parameters].any? { | param | param[:type] == 'File' }
+                    operation.merge!(consumes: ['multipart/form-data'])
+                  end
+                  operation.merge!(responseMessages: http_codes) unless http_codes.empty?
+
+                  if route.route_entity
+                    type = parse_entity_name(route.route_entity)
+                    if route.instance_variable_get(:@options)[:is_array]
+                      operation.merge!(
+                        'type' => 'array',
+                        'items' => generate_typeref(type)
+                      )
+                    else
+                      operation.merge!('type' => type)
+                    end
+                  end
+
+                  operation[:nickname] = route.route_nickname if route.route_nickname
+                  operation
+                end.compact
+                apis << {
+                  path: path,
+                  operations: operations
+                }
+              end
+
+              api_description = {
+                apiVersion:     api_version,
+                swaggerVersion: '1.2',
+                resourcePath:   "/#{params[:name]}",
+                produces:       content_types_for(target_class),
+                apis:           apis
+              }
+
+              base_path                        = parse_base_path(base_path, request)
+              api_description[:basePath]       = base_path if base_path && base_path.size > 0 && root_base_path != false
+              api_description[:models]         = parse_entity_models(models) unless models.empty?
+              api_description[:authorizations] = authorizations if authorizations
+
+              api_description
+            end
+          end
+
+          helpers do
+
+            def as_markdown(description)
+              description && @@markdown ? Kramdown::Document.new(strip_heredoc(description), input: 'GFM', enable_coderay: false).to_html : description
+            end
+
+            def parse_params(params, path, method)
+              params ||= []
+              params.map do |param, value|
+                value[:type] = 'File' if value.is_a?(Hash) && value[:type] == 'Rack::Multipart::UploadedFile'
+                items = {}
+
+                raw_data_type = value.is_a?(Hash) ? (value[:type] || 'string').to_s : 'string'
+                data_type     = case raw_data_type
+                                when 'Boolean', 'Date', 'Integer', 'String'
+                                  raw_data_type.downcase
+                                when 'BigDecimal'
+                                  'long'
+                                when 'DateTime'
+                                  'dateTime'
+                                when 'Numeric'
+                                  'double'
+                                else
+                                  parse_entity_name(raw_data_type)
+                                end
+                description   = value.is_a?(Hash) ? value[:desc] || value[:description] : ''
+                required      = value.is_a?(Hash) ? !!value[:required] : false
+                default_value = value.is_a?(Hash) ? value[:default] : nil
+                is_array      = value.is_a?(Hash) ? (value[:is_array] || false) : false
+                enum_values   = value.is_a?(Hash) ? value[:values] : nil
+                enum_values   = enum_values.call if enum_values && enum_values.is_a?(Proc)
+
+                if value.is_a?(Hash) && value.key?(:param_type)
+                  param_type  = value[:param_type]
+                  if is_array
+                    items     = { '$ref' => data_type }
+                    data_type = 'array'
+                  end
+                else
+                  param_type  = case
+                                when path.include?(":#{param}")
+                                  'path'
+                                when %w(POST PUT PATCH).include?(method)
+                                  if is_primitive?(data_type)
+                                    'form'
+                                  else
+                                    'body'
+                                  end
+                                else
+                                  'query'
+                                end
+                end
+                name          = (value.is_a?(Hash) && value[:full_name]) || param
+
+                parsed_params = {
+                  paramType:     param_type,
+                  name:          name,
+                  description:   as_markdown(description),
+                  type:          data_type,
+                  required:      required,
+                  allowMultiple: is_array
+                }
+                parsed_params.merge!(format: 'int32') if data_type == 'integer'
+                parsed_params.merge!(format: 'int64') if data_type == 'long'
+                parsed_params.merge!(items: items) if items.present?
+                parsed_params.merge!(defaultValue: default_value) if default_value
+                parsed_params.merge!(enum: enum_values) if enum_values
+                parsed_params
+              end
+            end
+
+            def content_types_for(target_class)
+              content_types = (target_class.settings[:content_types] || {}).values
+
+              if content_types.empty?
+                formats       = [target_class.settings[:format], target_class.settings[:default_format]].compact.uniq
+                formats       = Grape::Formatter::Base.formatters({}).keys if formats.empty?
+                content_types = Grape::ContentTypes::CONTENT_TYPES.select { |content_type, _mime_type| formats.include? content_type }.values
+              end
+
+              content_types.uniq
+            end
+
+            def parse_info(info)
+              {
+                contact:            info[:contact],
+                description:        as_markdown(info[:description]),
+                license:            info[:license],
+                licenseUrl:         info[:license_url],
+                termsOfServiceUrl:  info[:terms_of_service_url],
+                title:              info[:title]
+              }.delete_if { |_, value| value.blank? }
+            end
+
+            def parse_header_params(params)
+              params ||= []
+
+              params.map do |param, value|
+                data_type     = 'String'
+                description   = value.is_a?(Hash) ? value[:description] : ''
+                required      = value.is_a?(Hash) ? !!value[:required] : false
+                default_value = value.is_a?(Hash) ? value[:default] : nil
+                param_type    = 'header'
+
+                parsed_params = {
+                  paramType:    param_type,
+                  name:         param,
+                  description:  as_markdown(description),
+                  type:         data_type,
+                  required:     required
+                }
+
+                parsed_params.merge!(defaultValue: default_value) if default_value
+
+                parsed_params
+              end
+            end
+
+            def parse_path(path, version)
+              # adapt format to swagger format
+              parsed_path = path.gsub('(.:format)', @@hide_format ? '' : '.{format}')
+              # This is attempting to emulate the behavior of
+              # Rack::Mount::Strexp. We cannot use Strexp directly because
+              # all it does is generate regular expressions for parsing URLs.
+              # TODO: Implement a Racc tokenizer to properly generate the
+              # parsed path.
+              parsed_path = parsed_path.gsub(/:([a-zA-Z_]\w*)/, '{\1}')
+              # add the version
+              version ? parsed_path.gsub('{version}', version) : parsed_path
+            end
+
+            def parse_entity_name(model)
+              if model.respond_to?(:entity_name)
+                model.entity_name
+              else
+                name = model.to_s
+                entity_parts = name.split('::')
+                entity_parts.reject! { |p| p == 'Entity' || p == 'Entities' }
+                entity_parts.join('::')
+              end
+            end
+
+            def parse_entity_models(models)
+              result = {}
+              models.each do |model|
+                name       = parse_entity_name(model)
+                properties = {}
+                required   = []
+
+                model.documentation.each do |property_name, property_info|
+                  p = property_info.dup
+
+                  required << property_name.to_s if p.delete(:required)
+
+                  if p.delete(:is_array)
+                    p[:items] = generate_typeref(p[:type])
+                    p[:type] = 'array'
+                  else
+                    p.merge! generate_typeref(p.delete(:type))
+                  end
+
+                  # rename Grape Entity's "desc" to "description"
+                  property_description = p.delete(:desc)
+                  p[:description] = property_description if property_description
+
+                  # rename Grape's 'values' to 'enum'
+                  select_values = p.delete(:values)
+                  if select_values
+                    select_values = select_values.call if select_values.is_a?(Proc)
+                    p[:enum] = select_values
+                  end
+
+                  properties[property_name] = p
+
+                end
+
+                result[name] = {
+                  id:         model.instance_variable_get(:@root) || name,
+                  properties: properties
+                }
+                result[name].merge!(required: required) unless required.empty?
+              end
+
+              result
+            end
+
+            def models_with_included_presenters(models)
+              all_models = models
+
+              models.each do |model|
+                # get model references from exposures with a documentation
+                additional_models = model.exposures.map do |_, config|
+                  config[:using] if config.key?(:documentation)
+                end.compact
+
+                all_models += additional_models
+              end
+
+              all_models
+            end
+
+            def is_primitive?(type)
+              %w(integer long float double string byte boolean date dateTime).include? type
+            end
+
+            def generate_typeref(type)
+              if is_primitive? type
+                { 'type' => type }
+              else
+                { '$ref' => type }
+              end
+            end
+
+            def parse_http_codes(codes, models)
+              codes ||= {}
+              codes.map do |k, v, m|
+                models << m if m
+                http_code_hash = {
+                  code: k,
+                  message: v
+                }
+                http_code_hash[:responseModel] = parse_entity_name(m) if m
+                http_code_hash
+              end
+            end
+
+            def try(*args, &block)
+              if args.empty? && block_given?
+                yield self
+              elsif respond_to?(args.first)
+                public_send(*args, &block)
+              end
+            end
+
+            def strip_heredoc(string)
+              indent = string.scan(/^[ \t]*(?=\S)/).min.try(:size) || 0
+              string.gsub(/^[ \t]{#{indent}}/, '')
+            end
+
+            def parse_base_path(base_path, request)
+              if base_path.is_a?(Proc)
+                base_path.call(request)
+              elsif base_path.is_a?(String)
+                URI(base_path).relative? ? URI.join(request.base_url, base_path).to_s : base_path
+              else
+                request.base_url
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end