grape-swagger 0.11.0 → 0.20.0

data/lib/grape-swagger/doc_methods/data_type.rb

@@ -0,0 +1,77 @@
+module GrapeSwagger
+  module DocMethods
+    class DataType
+      class << self
+        def call(value)
+          raw_data_type = value[:type] if value.is_a?(Hash)
+          raw_data_type = value unless value.is_a?(Hash)
+          raw_data_type ||= 'string'
+          case raw_data_type.to_s
+          when 'Boolean', 'Date', 'Integer', 'String', 'Float', 'JSON', 'Array'
+            raw_data_type.to_s.downcase
+          when 'Hash'
+            'object'
+          when 'Rack::Multipart::UploadedFile', 'File'
+            'file'
+          when 'Virtus::Attribute::Boolean'
+            'boolean'
+          when 'BigDecimal'
+            'double'
+          when 'DateTime', 'Time'
+            'dateTime'
+          when 'Numeric'
+            'long'
+          when 'Symbol'
+            'string'
+          else
+            parse_entity_name(raw_data_type)
+          end
+        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 request_primitive?(type)
+          request_primitives.include?(type.to_s.downcase)
+        end
+
+        def primitive?(type)
+          primitives.include?(type.to_s.downcase)
+        end
+
+        def request_primitives
+          primitives + %w(object string boolean file json array)
+        end
+
+        def primitives
+          PRIMITIVE_MAPPINGS.keys.map(&:downcase)
+        end
+
+        def mapping(value)
+          PRIMITIVE_MAPPINGS[value] || 'string'
+        end
+      end
+
+      PRIMITIVE_MAPPINGS = {
+        'integer' => %w(integer int32),
+        'long' => %w(integer int64),
+        'float' => %w(number float),
+        'double' => %w(number double),
+        'byte' => %w(string byte),
+        'date' => %w(string date),
+        'dateTime' => %w(string date-time),
+        'binary' => %w(string binary),
+        'password' => %w(string password),
+        'email' => %w(string email)
+      }.freeze
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/extensions.rb

@@ -0,0 +1,75 @@
+module GrapeSwagger
+  module DocMethods
+    class Extensions
+      class << self
+        def add(path, definitions, route)
+          @route = route
+          description = route.route_settings[:description]
+          add_extension_to(path[method], extension(description)) if description && extended?(description, :x)
+
+          settings = route.route_settings
+          add_extensions_to_path(settings, path) if settings && extended?(settings, :x_path)
+          add_extensions_to_definition(settings, path, definitions) if settings && extended?(settings, :x_def)
+        end
+
+        def add_extensions_to_path(settings, path)
+          add_extension_to(path, extension(settings, :x_path))
+        end
+
+        def add_extensions_to_definition(settings, path, definitions)
+          def_extension = extension(settings, :x_def)
+
+          if def_extension[:x_def].is_a?(Array)
+            def_extension[:x_def].each do |extension|
+              next unless extension.key?(:for)
+              status = extension.delete(:for)
+              definition = find_definition(status, path)
+              add_extension_to(definitions[definition], x_def: extension)
+            end
+          else
+            return unless def_extension[:x_def].key?(:for)
+            status = def_extension[:x_def].delete(:for)
+            definition = find_definition(status, path)
+            add_extension_to(definitions[definition], def_extension)
+          end
+        end
+
+        def find_definition(status, path)
+          response = path[method][:responses][status]
+
+          response[:schema]['$ref'].split('/').last
+        end
+
+        def add_extension_to(part, extensions)
+          concatenate(extensions).each do |key, value|
+            part[key] = value
+          end
+        end
+
+        def concatenate(extensions)
+          result = {}
+
+          extensions.values.each do |extension|
+            extension.each do |key, value|
+              result["x-#{key}"] = value
+            end
+          end
+
+          result
+        end
+
+        def extended?(part, identifier = :x)
+          !extension(part, identifier).empty?
+        end
+
+        def extension(part, identifier = :x)
+          part.select { |x| x == identifier }
+        end
+
+        def method
+          @route.route_method.downcase.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/move_params.rb

@@ -0,0 +1,153 @@
+module GrapeSwagger
+  module DocMethods
+    class MoveParams
+      class << self
+        def to_definition(paths, definitions)
+          @definitions = definitions
+          find_post_put(paths) do |path|
+            find_definition_and_params(path)
+          end
+        end
+
+        def find_post_put(paths)
+          paths.each do |x|
+            found = x.last.select { |y| move_methods.include?(y) }
+            yield found unless found.empty?
+          end
+        end
+
+        def find_definition_and_params(path)
+          path.keys.each do |verb|
+            params = path[verb][:parameters]
+
+            next if params.nil?
+            next unless should_move?(params)
+
+            unify!(params)
+
+            status_code = GrapeSwagger::DocMethods::StatusCodes.get[verb.to_sym][:code]
+            response = path[verb][:responses][status_code]
+            referenced_definition = parse_model(response[:schema]['$ref'])
+
+            name = build_definition(referenced_definition, verb)
+            move_params_to_new(name, params)
+
+            @definitions[name][:description] = path[verb][:description]
+            path[verb][:parameters] << build_body_parameter(response.dup, name)
+          end
+        end
+
+        def move_params_to_new(name, params)
+          properties = {}
+          definition = @definitions[name]
+
+          nested_definitions(name, params, properties)
+
+          params.dup.each do |param|
+            next unless movable?(param)
+
+            name = param[:name].to_sym
+            properties[name] = {}
+
+            properties[name].tap do |x|
+              property_keys.each do |attribute|
+                x[attribute] = param[attribute] unless param[attribute].nil?
+              end
+            end
+
+            properties[name][:readOnly] = true unless deletable?(param)
+            params.delete(param) if deletable?(param)
+
+            definition[:required] << name if deletable?(param) && param[:required]
+          end
+
+          definition.delete(:required) if definition[:required].empty?
+          definition[:properties] = properties
+        end
+
+        def nested_definitions(name, params, properties)
+          loop do
+            nested_name = params.bsearch { |x| x[:name].include?('[') }
+            return if nested_name.nil?
+
+            nested_name = nested_name[:name].split('[').first
+
+            nested, = params.partition { |x| x[:name].start_with?("#{nested_name}[") }
+            nested.each { |x| params.delete(x) }
+            nested_def_name = GrapeSwagger::DocMethods::OperationId.manipulate(nested_name)
+            def_name = "#{name}#{nested_def_name}"
+            properties[nested_name] = { '$ref' => "#/definitions/#{def_name}" }
+
+            prepare_nested_names(nested)
+            build_definition(def_name)
+            @definitions[def_name][:description] = "#{name} - #{nested_name}"
+            move_params_to_new(def_name, nested)
+          end
+        end
+
+        private
+
+        def build_body_parameter(response, name = false)
+          body_param = {}
+          body_param.tap do |x|
+            x[:name] = parse_model(response[:schema]['$ref'])
+            x[:in] = 'body'
+            x[:required] = true
+            x[:schema] = { '$ref' => response[:schema]['$ref'] } unless name
+            x[:schema] = { '$ref' => "#/definitions/#{name}" } if name
+          end
+        end
+
+        def build_definition(name, verb = nil)
+          name = "#{verb}Request#{name}" if verb
+          @definitions[name] = { type: 'object', properties: {}, required: [] }
+
+          name
+        end
+
+        def prepare_nested_names(params)
+          params.each do |param|
+            param.tap do |x|
+              name = x[:name].partition('[').last.sub(']', '')
+              name = name.partition('[').last.sub(']', '') if name.start_with?('[')
+              x[:name] = name
+            end
+          end
+        end
+
+        def unify!(params)
+          params.each do |param|
+            param[:in] = param.delete(:param_type) if param.key?(:param_type)
+            param[:in] = 'body' if param[:in] == 'formData'
+          end
+        end
+
+        def parse_model(ref)
+          ref.split('/').last
+        end
+
+        def move_methods
+          [:post, :put, :patch]
+        end
+
+        def property_keys
+          [:type, :format, :description, :minimum, :maximum, :items]
+        end
+
+        def movable?(param)
+          return true if param[:in] == 'body' || param[:in] == 'path'
+          false
+        end
+
+        def deletable?(param)
+          return true if movable?(param) && param[:in] == 'body'
+          false
+        end
+
+        def should_move?(params)
+          !params.select { |x| x[:in] == 'body' || x[:param_type] == 'body' }.empty?
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/operation_id.rb

@@ -0,0 +1,27 @@
+module GrapeSwagger
+  module DocMethods
+    class OperationId
+      class << self
+        def build(method = nil, path = nil)
+          verb = method.to_s.downcase
+
+          operation = manipulate(path) unless path.nil?
+
+          "#{verb}#{operation}"
+        end
+
+        def manipulate(path)
+          operation = path.split('/').map(&:capitalize).join
+          operation.gsub!(/\-(\w)/, &:upcase).delete!('-') if operation.include?('-')
+          operation.gsub!(/\_(\w)/, &:upcase).delete!('_') if operation.include?('_')
+          if path.include?('{')
+            operation.gsub!(/\{(\w)/, &:upcase)
+            operation.delete!('{').delete!('}')
+          end
+
+          operation
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/optional_object.rb

@@ -0,0 +1,15 @@
+module GrapeSwagger
+  module DocMethods
+    class OptionalObject
+      class << self
+        def build(key, options, request = nil)
+          if options[key]
+            options[key].is_a?(Proc) ? options[key].call : options[key]
+          else
+            request
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/parse_params.rb

@@ -0,0 +1,113 @@
+module GrapeSwagger
+  module DocMethods
+    class ParseParams
+      class << self
+        def call(param, settings, route)
+          path = route.route_path
+          method = route.route_method
+
+          data_type = GrapeSwagger::DocMethods::DataType.call(settings)
+          additional_documentation = settings[:documentation]
+          if additional_documentation
+            settings = additional_documentation.merge(settings)
+          end
+
+          value_type = settings.merge(data_type: data_type, path: path, param_name: param, method: method)
+
+          @parsed_param = {
+            in:            param_type(value_type),
+            name:          settings[:full_name] || param,
+            description:   settings[:desc] || settings[:description] || nil
+          }
+
+          document_type_and_format(data_type)
+          document_array_param(value_type)
+          document_default_value(settings)
+          document_range_values(settings)
+          document_required(settings)
+
+          @parsed_param
+        end
+
+        private
+
+        def document_required(settings)
+          @parsed_param[:required] = settings[:required] || false
+          @parsed_param[:required] = true if @parsed_param[:in] == 'path'
+        end
+
+        def document_range_values(settings)
+          values               = settings[:values] || nil
+          enum_or_range_values = parse_enum_or_range_values(values)
+          @parsed_param.merge!(enum_or_range_values) if enum_or_range_values
+        end
+
+        def document_default_value(settings)
+          default_value = settings[:default] || nil
+          example       = settings[:example] || nil
+
+          @parsed_param[:default] = example if example
+          @parsed_param[:default] = default_value if default_value && example.blank?
+        end
+
+        def document_type_and_format(data_type)
+          if GrapeSwagger::DocMethods::DataType.primitive?(data_type)
+            data = GrapeSwagger::DocMethods::DataType.mapping(data_type)
+            @parsed_param[:type], @parsed_param[:format] = data
+          else
+            @parsed_param[:type] = data_type
+          end
+        end
+
+        def document_array_param(value_type)
+          if value_type[:is_array]
+            if value_type[:documentation].present?
+              param_type = value_type[:documentation][:param_type]
+              type = GrapeSwagger::DocMethods::DataType.mapping(value_type[:documentation][:type])
+            end
+            array_items = { 'type' => type || value_type[:data_type] }
+
+            @parsed_param[:in] = param_type || 'formData'
+            @parsed_param[:items] = array_items
+            @parsed_param[:type] = 'array'
+            @parsed_param.delete(:format)
+          end
+        end
+
+        def param_type(value_type)
+          param_type = value_type[:param_type] || value_type[:in]
+          case
+          when value_type[:path].include?("{#{value_type[:param_name]}}")
+            'path'
+          when param_type
+            param_type
+          when %w(POST PUT PATCH).include?(value_type[:method])
+            GrapeSwagger::DocMethods::DataType.request_primitive?(value_type[:data_type]) ? 'formData' : 'body'
+          else
+            'query'
+          end
+        end
+
+        def parse_enum_or_range_values(values)
+          case values
+          when Range
+            parse_range_values(values) if values.first.is_a?(Integer)
+          when Proc
+            values_result = values.call
+            if values_result.is_a?(Range) && values_result.first.is_a?(Integer)
+              parse_range_values(values_result)
+            else
+              { enum: values_result }
+            end
+          else
+            { enum: values } if values
+          end
+        end
+
+        def parse_range_values(values)
+          { minimum: values.first, maximum: values.last }
+        end
+      end
+    end
+  end
+end