gitlab-grape-swagger 1.5.0

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class BuildModelDefinition
+      class << self
+        def build(_model, properties, required, other_def_properties = {})
+          definition = { type: 'object', properties: properties }.merge(other_def_properties)
+
+          definition[:required] = required if required.is_a?(Array) && required.any?
+
+          definition
+        end
+
+        def parse_params_from_model(parsed_response, model, model_name)
+          if parsed_response.is_a?(Hash) && parsed_response.keys.first == :allOf
+            refs_or_models = parsed_response[:allOf]
+            parsed = parse_refs_and_models(refs_or_models, model)
+
+            {
+              allOf: parsed
+            }
+          else
+            properties, required = parsed_response
+            unless properties&.any?
+              raise GrapeSwagger::Errors::SwaggerSpec,
+                    "Empty model #{model_name}, swagger 2.0 doesn't support empty definitions."
+            end
+            properties, other_def_properties = parse_properties(properties)
+
+            build(
+              model, properties, required, other_def_properties
+            )
+          end
+        end
+
+        def parse_properties(properties)
+          other_properties = {}
+
+          discriminator_key, discriminator_value =
+            properties.find do |_key, value|
+              value[:documentation].try(:[], :is_discriminator)
+            end
+
+          if discriminator_key
+            discriminator_value.delete(:documentation)
+            properties[discriminator_key] = discriminator_value
+
+            other_properties[:discriminator] = discriminator_key
+          end
+
+          [properties, other_properties]
+        end
+
+        def parse_refs_and_models(refs_or_models, model)
+          refs_or_models.map do |ref_or_models|
+            if ref_or_models.is_a?(Hash) && ref_or_models.keys.first == '$ref'
+              ref_or_models
+            else
+              properties, required = ref_or_models
+              GrapeSwagger::DocMethods::BuildModelDefinition.build(model, properties, required)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class DataType
+      class << self
+        def call(value)
+          raw_data_type = value.is_a?(Hash) ? value[:type] : value
+          raw_data_type ||= 'String'
+          raw_data_type = parse_multi_type(raw_data_type)
+
+          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 'Grape::API::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_multi_type(raw_data_type)
+          case raw_data_type
+          when /\A\[.*\]\z/
+            type_as_string = raw_data_type.gsub(/[\[\s+\]]/, '').split(',').first
+            begin
+              Object.const_get(type_as_string)
+            rescue NameError
+              type_as_string
+            end
+          when Array
+            raw_data_type.first
+          else
+            raw_data_type
+          end
+        end
+
+        def parse_entity_name(model)
+          if model.respond_to?(:entity_name)
+            model.entity_name
+          elsif model.to_s.end_with?('::Entity', '::Entities')
+            model.to_s.split('::')[0..-2].join('_')
+          elsif model.to_s.start_with?('Entity::', 'Entities::', 'Representable::')
+            model.to_s.split('::')[1..-1].join('_')
+          else
+            model.to_s.split('::').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 query_array_primitive?(type)
+          query_array_primitives.include?(type.to_s.downcase)
+        end
+
+        def query_array_primitives
+          primitives << 'string'
+        end
+
+        def mapping(value)
+          PRIMITIVE_MAPPINGS[value] || 'string'
+        end
+
+        def collections
+          %w[csv ssv tsv pipes multi brackets]
+        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],
+        'uuid' => %w[string uuid]
+      }.freeze
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class Extensions
+      class << self
+        def add(path, definitions, route)
+          @route = route
+
+          description = route.settings[:description]
+          add_extension_to(path[method], extension(description)) if description && extended?(description, :x)
+
+          settings = route.settings
+          add_extensions_to_operation(settings, path, route) if settings && extended?(settings, :x_operation)
+          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_root(settings, object)
+          add_extension_to(object, extension(settings)) if extended?(settings, :x)
+        end
+
+        def add_extensions_to_info(settings, info)
+          add_extension_to(info, extension(settings)) if extended?(settings, :x)
+        end
+
+        def add_extensions_to_operation(settings, path, route)
+          add_extension_to(path[route.request_method.downcase.to_sym], extension(settings, :x_operation))
+        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 { |extension| setup_definition(extension, path, definitions) }
+          else
+            setup_definition(def_extension[:x_def], path, definitions)
+          end
+        end
+
+        def setup_definition(def_extension, path, definitions)
+          return unless def_extension.key?(:for)
+
+          status = def_extension[:for]
+
+          definition = find_definition(status, path)
+          add_extension_to(definitions[definition], x_def: def_extension)
+        end
+
+        def find_definition(status, path)
+          response = path[method][:responses][status]
+          return if response.nil?
+
+          return response[:schema]['$ref'].split('/').last if response[:schema].key?('$ref')
+          return response[:schema]['items']['$ref'].split('/').last if response[:schema].key?('items')
+        end
+
+        def add_extension_to(part, extensions)
+          return if part.nil?
+
+          concatenate(extensions).each do |key, value|
+            part[key] = value unless key.start_with?('x-for')
+          end
+        end
+
+        def concatenate(extensions)
+          result = {}
+
+          extensions.each_value 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(*args)
+          # We're shadowing Object.method(:symbol) here so we provide
+          # a compatibility layer for code that introspects the methods
+          # of this class
+          return super if args.size.positive?
+
+          @route.request_method.downcase.to_sym
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class FileParams
+      class << self
+        def includes_file_param?(params)
+          return params.any? { |x| x[:type] == 'file' }
+        end
+
+        def to_formdata(params)
+          params.each { |x| x[:in] = 'formData' if x[:in] == 'body' }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class FormatData
+      class << self
+        def to_format(parameters)
+          parameters.reject { |parameter| parameter[:in] == 'body' }.each do |b|
+            related_parameters = parameters.select do |p|
+              p[:name] != b[:name] && p[:name].to_s.start_with?("#{b[:name].to_s.gsub(/\[\]\z/, '')}[")
+            end
+            parameters.reject! { |p| p[:name] == b[:name] } if move_down(b, related_parameters)
+          end
+          parameters
+        end
+
+        def move_down(parameter, related_parameters)
+          case parameter[:type]
+          when 'array'
+            add_array(parameter, related_parameters)
+            unless related_parameters.blank?
+              add_braces(parameter, related_parameters) if parameter[:name].match?(/\A.*\[\]\z/)
+              return true
+            end
+          when 'object'
+            return true
+          end
+          false
+        end
+
+        def add_braces(parameter, related_parameters)
+          param_name = parameter[:name].gsub(/\A(.*)\[\]\z/, '\1')
+          related_parameters.each { |p| p[:name] = p[:name].gsub(param_name, "#{param_name}[]") }
+        end
+
+        def add_array(parameter, related_parameters)
+          related_parameters.each do |p|
+            next if p.key?(:items)
+
+            p_type = p[:type] == 'array' ? 'string' : p[:type]
+            p[:items] = { type: p_type, format: p[:format], enum: p[:enum], is_array: p[:is_array] }
+            p[:items].delete_if { |_k, v| v.nil? }
+            p[:type] = 'array'
+            p[:is_array] = parameter[:is_array]
+            p.delete(:format)
+            p.delete(:enum)
+            p.delete_if { |_k, v| v.nil? }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class Headers
+      class << self
+        def parse(route)
+          route.headers.to_a.map do |route_header|
+            route_header.tap do |header|
+              hash = header[1]
+              description = hash.delete('description')
+              hash[:documentation] = { desc: description, in: 'header' }
+              hash[:type] = hash['type'].titleize if hash['type']
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/deep_merge'
+
+module GrapeSwagger
+  module DocMethods
+    class MoveParams
+      class << self
+        attr_accessor :definitions
+
+        def can_be_moved?(http_verb, params)
+          move_methods.include?(http_verb) && includes_body_param?(params)
+        end
+
+        def to_definition(path, params, route, definitions)
+          @definitions = definitions
+          unify!(params)
+
+          params_to_move = movable_params(params)
+
+          return (params + correct_array_param(params_to_move)) if should_correct_array?(params_to_move)
+
+          params << parent_definition_of_params(params_to_move, path, route)
+
+          params
+        end
+
+        private
+
+        def should_correct_array?(param)
+          param.length == 1 && param.first[:in] == 'body' && param.first[:type] == 'array'
+        end
+
+        def correct_array_param(param)
+          param.first[:schema] = { type: param.first.delete(:type), items: param.first.delete(:items) }
+
+          param
+        end
+
+        def parent_definition_of_params(params, path, route)
+          definition_name = OperationId.build(route, path)
+          build_definition(definition_name, params)
+          definition = @definitions[definition_name]
+
+          move_params_to_new(definition, params)
+
+          definition[:description] = route.description if route.try(:description)
+
+          build_body_parameter(definition_name, route.options)
+        end
+
+        def move_params_to_new(definition, params)
+          params, nested_params = params.partition { |x| !x[:name].to_s.include?('[') }
+          params.each do |param|
+            property = param[:name]
+            param_properties, param_required = build_properties([param])
+            add_properties_to_definition(definition, param_properties, param_required)
+            related_nested_params, nested_params = nested_params.partition { |x| x[:name].start_with?("#{property}[") }
+            prepare_nested_names(property, related_nested_params)
+
+            next if related_nested_params.blank?
+
+            nested_definition = if should_expose_as_array?([param])
+                                  move_params_to_new(array_type, related_nested_params)
+                                else
+                                  move_params_to_new(object_type, related_nested_params)
+                                end
+            if definition.key?(:items)
+              definition[:items][:properties][property.to_sym].deep_merge!(nested_definition)
+            else
+              definition[:properties][property.to_sym].deep_merge!(nested_definition)
+            end
+          end
+          definition
+        end
+
+        def build_properties(params)
+          properties = {}
+          required = []
+
+          params.each do |param|
+            name = param[:name].to_sym
+
+            properties[name] = if should_expose_as_array?([param])
+                                 document_as_array(param)
+                               else
+                                 document_as_property(param)
+                               end
+
+            required << name if deletable?(param) && param[:required]
+          end
+
+          [properties, required]
+        end
+
+        def document_as_array(param)
+          {}.tap do |property|
+            property[:type] = 'array'
+            property[:description] = param.delete(:description) unless param[:description].nil?
+            property[:items] = document_as_property(param)[:items]
+          end
+        end
+
+        def document_as_property(param)
+          property_keys.each_with_object({}) do |x, memo|
+            next unless param.key?(x)
+
+            value = param[x]
+            if x == :type && @definitions[value].present?
+              memo['$ref'] = "#/definitions/#{value}"
+            else
+              memo[x] = value
+            end
+          end
+        end
+
+        def movable_params(params)
+          to_delete = params.each_with_object([]) { |x, memo| memo << x if deletable?(x) }
+          delete_from(params, to_delete)
+
+          to_delete
+        end
+
+        def delete_from(params, to_delete)
+          to_delete.each { |x| params.delete(x) }
+        end
+
+        def add_properties_to_definition(definition, properties, required)
+          if definition.key?(:items)
+            definition[:items][:properties].deep_merge!(properties)
+            add_to_required(definition[:items], required)
+          else
+            definition[:properties].deep_merge!(properties)
+            add_to_required(definition, required)
+          end
+        end
+
+        def add_to_required(definition, value)
+          return if value.blank?
+
+          definition[:required] ||= []
+          definition[:required].push(*value)
+        end
+
+        def build_body_parameter(name, options)
+          {}.tap do |x|
+            x[:name] = options[:body_name] || name
+            x[:in] = 'body'
+            x[:required] = true
+            x[:schema] = { '$ref' => "#/definitions/#{name}" }
+          end
+        end
+
+        def build_definition(name, params)
+          @definitions[name] = should_expose_as_array?(params) ? array_type : object_type
+
+          name
+        end
+
+        def array_type
+          { type: 'array', items: { type: 'object', properties: {} } }
+        end
+
+        def object_type
+          { type: 'object', properties: {} }
+        end
+
+        def prepare_nested_names(property, params)
+          params.each { |x| x[:name] = x[:name].sub(property, '').sub('[', '').sub(']', '') }
+        end
+
+        def unify!(params)
+          params.each { |x| x[:in] = x.delete(:param_type) if x[:param_type] }
+          params.each { |x| x[:in] = 'body' if x[:in] == 'formData' } if includes_body_param?(params)
+        end
+
+        def parse_model(ref)
+          parts = ref.split('/')
+          parts.last.include?('{') ? parts[0..-2].join('/') : parts[0..-1].join('/')
+        end
+
+        def property_keys
+          %i[type format description minimum maximum items enum default additional_properties additionalProperties
+             example]
+        end
+
+        def deletable?(param)
+          param[:in] == 'body'
+        end
+
+        def move_methods
+          [:post, :put, :patch, 'POST', 'PUT', 'PATCH']
+        end
+
+        def includes_body_param?(params)
+          params.any? { |x| x[:in] == 'body' || x[:param_type] == 'body' }
+        end
+
+        def should_expose_as_array?(params)
+          should_exposed_as(params) == 'array'
+        end
+
+        def should_exposed_as(params)
+          params.any? { |x| x[:type] && x[:type] != 'array' } ? 'object' : 'array'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class OperationId
+      class << self
+        def build(route, path = nil)
+          if route.options[:nickname]
+            route.options[:nickname]
+          else
+            verb = route.request_method.to_s.downcase
+            operation = manipulate(path) unless path.nil?
+            "#{verb}#{operation}"
+          end
+        end
+
+        def manipulate(path)
+          operation = path.split('/').map(&:capitalize).join
+          operation.gsub!(/-(\w)/, &:upcase).delete!('-') if operation[/-(\w)/]
+          operation.gsub!(/_(\w)/, &:upcase).delete!('_') if operation.include?('_')
+          operation.gsub!(/\.(\w)/, &:upcase).delete!('.') if operation[/\.(\w)/]
+          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,30 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class OptionalObject
+      class << self
+        def build(key, options, request = nil)
+          if options[key]
+            return evaluate(key, options, request) if options[key].is_a?(Proc)
+
+            options[key]
+          else
+            request.send(default_values[key])
+          end
+        end
+
+        def evaluate(key, options, request)
+          options[key].arity.zero? ? options[key].call : options[key].call(request)
+        end
+
+        def default_values
+          {
+            host: 'host_with_port',
+            base_path: 'script_name'
+          }
+        end
+      end
+    end
+  end
+end