grape-oas 1.0.0

data/lib/grape_oas/api_model_builders/request_params.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "request_params_support/param_location_resolver"
+require_relative "request_params_support/param_schema_builder"
+require_relative "request_params_support/schema_enhancer"
+require_relative "request_params_support/nested_params_builder"
+
+module GrapeOAS
+  module ApiModelBuilders
+    class RequestParams
+      ROUTE_PARAM_REGEX = /(?<=:)\w+/
+
+      attr_reader :api, :route, :path_param_name_map
+
+      def initialize(api:, route:, path_param_name_map: nil)
+        @api = api
+        @route = route
+        @path_param_name_map = path_param_name_map || {}
+      end
+
+      def build
+        route_params = route.path.scan(ROUTE_PARAM_REGEX)
+        all_params = route.options[:params] || {}
+
+        # Check if we have nested params (bracket notation)
+        has_nested = all_params.keys.any? { |k| k.include?("[") }
+
+        if has_nested
+          build_with_nested_params(all_params, route_params)
+        else
+          build_flat_params(all_params, route_params)
+        end
+      end
+
+      private
+
+      # Builds params when nested structures are detected.
+      def build_with_nested_params(all_params, route_params)
+        body_schema = nested_params_builder.build(all_params, path_params: route_params)
+        non_body_params = extract_non_body_params(all_params, route_params)
+
+        [body_schema, non_body_params]
+      end
+
+      # Builds params for flat (non-nested) structures.
+      def build_flat_params(all_params, route_params)
+        body_schema = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+        path_params = []
+
+        all_params.each do |name, spec|
+          next if location_resolver.hidden_parameter?(spec)
+
+          location = location_resolver.resolve(
+            name: name,
+            spec: spec,
+            route_params: route_params,
+            route: route,
+          )
+          required = spec[:required] || false
+          schema = schema_builder.build(spec)
+          mapped_name = path_param_name_map.fetch(name, name)
+
+          if location == "body"
+            body_schema.add_property(name, schema, required: required)
+          else
+            path_params << build_parameter(mapped_name, location, required, schema, spec)
+          end
+        end
+
+        [body_schema, path_params]
+      end
+
+      # Extracts non-body params (path, query, header) from flat params.
+      def extract_non_body_params(all_params, route_params)
+        params = []
+
+        all_params.each do |name, spec|
+          # Skip nested params (they go into body)
+          next if name.include?("[")
+          # Skip Hash/body params
+          next if location_resolver.body_param?(spec)
+          # Skip hidden params
+          next if location_resolver.hidden_parameter?(spec)
+
+          location = location_resolver.resolve(
+            name: name,
+            spec: spec,
+            route_params: route_params,
+            route: route,
+          )
+          next if location == "body"
+
+          mapped_name = path_param_name_map.fetch(name, name)
+          params << build_parameter(mapped_name, location, spec[:required] || false, schema_builder.build(spec), spec)
+        end
+
+        params
+      end
+
+      def build_parameter(name, location, required, schema, spec)
+        ApiModel::Parameter.new(
+          location: location,
+          name: name,
+          required: required,
+          schema: schema,
+          description: spec[:documentation]&.dig(:desc),
+          collection_format: extract_collection_format(spec),
+        )
+      end
+
+      def extract_collection_format(spec)
+        spec.dig(:documentation, :collectionFormat) || spec.dig(:documentation, :collection_format)
+      end
+
+      def location_resolver
+        RequestParamsSupport::ParamLocationResolver
+      end
+
+      def schema_builder
+        @schema_builder ||= RequestParamsSupport::ParamSchemaBuilder.new
+      end
+
+      def nested_params_builder
+        @nested_params_builder ||= RequestParamsSupport::NestedParamsBuilder.new(schema_builder: schema_builder)
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/request_params_support/nested_params_builder.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module RequestParamsSupport
+      # Reconstructs nested parameter structures from Grape's flat bracket notation.
+      # Grape exposes nested params as flat keys like "address[street]", "address[city]".
+      # This class converts them back to proper nested schemas.
+      class NestedParamsBuilder
+        BRACKET_PATTERN = /\[([^\]]+)\]/
+        MAX_NESTING_DEPTH = 10
+
+        def initialize(schema_builder:)
+          @schema_builder = schema_builder
+        end
+
+        # Builds a nested schema from flat bracket-notation params.
+        #
+        # @param flat_params [Hash] the flat params from Grape route (name => spec)
+        # @param path_params [Array<String>] names of path parameters to exclude
+        # @return [ApiModel::Schema] the reconstructed nested schema
+        def build(flat_params, path_params: [])
+          schema = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+
+          # Separate top-level params from nested bracket params
+          top_level, nested = partition_params(flat_params)
+
+          # Group nested params by their root key
+          nested_groups = group_nested_params(nested)
+
+          top_level.each do |name, spec|
+            next if path_params.include?(name)
+            next if ParamLocationResolver.explicit_non_body_param?(spec)
+            next if ParamLocationResolver.hidden_parameter?(spec)
+
+            child_schema = @schema_builder.build(spec)
+
+            # Check if this param has nested children
+            if nested_groups.key?(name)
+              nested_children = nested_groups[name]
+              child_schema = build_nested_children(spec, nested_children, depth: 0)
+            end
+
+            required = spec[:required] || false
+            schema.add_property(name, child_schema, required: required)
+          end
+
+          schema
+        end
+
+        private
+
+        # Partitions params into top-level (no brackets) and nested (with brackets).
+        def partition_params(flat_params)
+          top_level = {}
+          nested = {}
+
+          flat_params.each do |name, spec|
+            if name.include?("[")
+              nested[name] = spec
+            else
+              top_level[name] = spec
+            end
+          end
+
+          [top_level, nested]
+        end
+
+        # Groups nested params by their root key.
+        # "address[street]" => { "address" => { "street" => spec } }
+        def group_nested_params(nested_params)
+          groups = Hash.new { |h, k| h[k] = {} }
+
+          nested_params.each do |name, spec|
+            root, rest = parse_bracket_key(name)
+            groups[root][rest] = spec
+          end
+
+          groups
+        end
+
+        # Parses a bracket-notation key into root and remaining path.
+        # "address[street]" => ["address", "street"]
+        # "company[address][street]" => ["company", "address[street]"]
+        def parse_bracket_key(name)
+          match = name.match(/^([^\[]+)\[([^\]]+)\](.*)$/)
+          return [name, nil] unless match
+
+          root = match[1]
+          first_key = match[2]
+          remainder = match[3]
+
+          rest = remainder.empty? ? first_key : "#{first_key}#{remainder}"
+          [root, rest]
+        end
+
+        # Builds nested children schema recursively.
+        # @raise [ArgumentError] if nesting exceeds MAX_NESTING_DEPTH
+        def build_nested_children(parent_spec, nested_children, depth: 0)
+          raise ArgumentError, "Parameter nesting too deep (max #{MAX_NESTING_DEPTH} levels)" if depth > MAX_NESTING_DEPTH
+
+          parent_type = parent_spec[:type]
+
+          if array_type?(parent_type)
+            build_array_with_children(parent_spec, nested_children, depth: depth)
+          else
+            build_hash_with_children(parent_spec, nested_children, depth: depth)
+          end
+        end
+
+        # Checks if type represents an array (class or string "Array")
+        def array_type?(type)
+          type == Array || type.to_s == "Array"
+        end
+
+        # Builds an array schema with nested item properties.
+        def build_array_with_children(parent_spec, nested_children, depth: 0)
+          items_schema = build_hash_with_children(parent_spec, nested_children, depth: depth)
+          ApiModel::Schema.new(
+            type: Constants::SchemaTypes::ARRAY,
+            items: items_schema,
+          )
+        end
+
+        # Builds a hash/object schema with nested properties.
+        def build_hash_with_children(parent_spec, nested_children, depth: 0)
+          schema = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+          top_level, deeply_nested = partition_params(nested_children)
+          nested_groups = group_nested_params(deeply_nested)
+
+          top_level.each do |name, spec|
+            child_schema = if nested_groups.key?(name)
+                             build_nested_children(spec, nested_groups[name], depth: depth + 1)
+                           else
+                             @schema_builder.build(spec)
+                           end
+            schema.add_property(name, child_schema, required: spec[:required] || false)
+          end
+
+          apply_documentation_extensions(schema, parent_spec)
+          schema
+        end
+
+        def apply_documentation_extensions(schema, parent_spec)
+          doc = parent_spec[:documentation] || {}
+          schema.description = doc[:desc] if doc[:desc]
+          schema.additional_properties = doc[:additional_properties] if doc.key?(:additional_properties)
+          schema.unevaluated_properties = doc[:unevaluated_properties] if doc.key?(:unevaluated_properties)
+          schema.format = doc[:format] if doc[:format]
+          schema.examples = doc[:example] if doc[:example]
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/request_params_support/param_location_resolver.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module RequestParamsSupport
+      # Resolves the location (path, query, body, header) for a parameter.
+      class ParamLocationResolver
+        # Determines the location for a parameter.
+        #
+        # @param name [String] the parameter name
+        # @param spec [Hash] the parameter specification
+        # @param route_params [Array<String>] list of path parameter names
+        # @param route [Object] the Grape route object
+        # @return [String] the parameter location ("path", "query", "body", "header")
+        def self.resolve(name:, spec:, route_params:, route:)
+          return "path" if route_params.include?(name)
+
+          extract_from_spec(spec, route)
+        end
+
+        # Checks if a parameter should be in the request body.
+        #
+        # @param spec [Hash] the parameter specification
+        # @return [Boolean] true if it's a body parameter
+        def self.body_param?(spec)
+          spec.dig(:documentation, :param_type) == "body" || [Hash, "Hash"].include?(spec[:type])
+        end
+
+        # Checks if a parameter is explicitly marked as NOT a body param.
+        #
+        # @param spec [Hash] the parameter specification
+        # @return [Boolean] true if explicitly non-body
+        def self.explicit_non_body_param?(spec)
+          param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
+          param_type && %w[query header path].include?(param_type)
+        end
+
+        # Checks if a parameter should be hidden from documentation.
+        # Required parameters are never hidden (matching grape-swagger behavior).
+        #
+        # @param spec [Hash] the parameter specification
+        # @return [Boolean] true if hidden
+        def self.hidden_parameter?(spec)
+          return false if spec[:required]
+
+          hidden = spec.dig(:documentation, :hidden)
+          hidden = hidden.call if hidden.respond_to?(:call)
+          hidden
+        end
+
+        class << self
+          private
+
+          def extract_from_spec(spec, route)
+            # If body_name is set on the route, treat non-path params as body by default
+            return "body" if route.options[:body_name] && !spec.dig(:documentation, :param_type)
+
+            spec.dig(:documentation, :param_type)&.downcase || "query"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/request_params_support/param_schema_builder.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module RequestParamsSupport
+      # Builds OpenAPI schemas from Grape parameter specifications.
+      class ParamSchemaBuilder
+        include Concerns::TypeResolver
+        include Concerns::OasUtilities
+
+        # Builds a schema for a parameter specification.
+        #
+        # @param spec [Hash] the parameter specification
+        # @return [ApiModel::Schema] the built schema
+        def self.build(spec)
+          new.build(spec)
+        end
+
+        def build(spec)
+          doc = spec[:documentation] || {}
+          raw_type = spec[:type] || doc[:type]
+
+          schema = build_base_schema(spec, doc, raw_type)
+          SchemaEnhancer.apply(schema, spec, doc)
+          schema
+        end
+
+        private
+
+        def build_base_schema(spec, doc, raw_type)
+          type_source = spec[:type]
+          doc_type = doc[:type]
+
+          return build_entity_array_schema(spec, raw_type, doc_type) if entity_array_type?(type_source, doc_type, spec)
+          return build_doc_entity_array_schema(doc_type) if doc[:is_array] && grape_entity?(doc_type)
+          return build_entity_schema(doc_type) if grape_entity?(doc_type)
+          return build_entity_schema(raw_type) if grape_entity?(raw_type)
+          return build_elements_array_schema(spec) if array_with_elements?(raw_type, spec)
+          return build_multi_type_schema(raw_type) if multi_type?(raw_type)
+          return build_typed_array_schema(raw_type) if typed_array?(raw_type)
+          return build_simple_array_schema if simple_array?(raw_type)
+
+          build_primitive_schema(raw_type, doc)
+        end
+
+        def entity_array_type?(type_source, doc_type, spec)
+          (type_source == Array || type_source.to_s == "Array") &&
+            grape_entity?(doc_type || spec[:elements] || spec[:of])
+        end
+
+        def array_with_elements?(raw_type, spec)
+          (raw_type == Array || raw_type.to_s == "Array") && spec[:elements]
+        end
+
+        def build_entity_array_schema(spec, raw_type, doc_type)
+          entity_type = resolve_entity_class(extract_entity_type_from_array(spec, raw_type, doc_type))
+          items = entity_type ? Introspectors::EntityIntrospector.new(entity_type).build_schema : nil
+          items ||= ApiModel::Schema.new(type: sanitize_type(extract_entity_type_from_array(spec, raw_type)))
+          ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items)
+        end
+
+        def build_doc_entity_array_schema(doc_type)
+          entity_class = resolve_entity_class(doc_type)
+          items = Introspectors::EntityIntrospector.new(entity_class).build_schema
+          ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items)
+        end
+
+        def build_entity_schema(type)
+          entity_class = resolve_entity_class(type)
+          Introspectors::EntityIntrospector.new(entity_class).build_schema
+        end
+
+        def build_elements_array_schema(spec)
+          items_type = spec[:elements]
+          entity = resolve_entity_class(items_type)
+          items_schema = if entity
+                           Introspectors::EntityIntrospector.new(entity).build_schema
+                         else
+                           ApiModel::Schema.new(type: sanitize_type(items_type))
+                         end
+          ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
+        end
+
+        def build_simple_array_schema
+          ApiModel::Schema.new(
+            type: Constants::SchemaTypes::ARRAY,
+            items: ApiModel::Schema.new(type: Constants::SchemaTypes::STRING),
+          )
+        end
+
+        # Builds oneOf schema for Grape's multi-type notation like "[String, Integer]"
+        def build_multi_type_schema(type)
+          type_names = extract_multi_types(type)
+          schemas = type_names.map do |type_name|
+            ApiModel::Schema.new(type: resolve_schema_type(type_name))
+          end
+          ApiModel::Schema.new(one_of: schemas)
+        end
+
+        def build_primitive_schema(raw_type, doc)
+          ApiModel::Schema.new(
+            type: sanitize_type(raw_type),
+            description: doc[:desc],
+          )
+        end
+
+        def extract_entity_type_from_array(spec, raw_type, doc_type = nil)
+          return spec[:elements] if grape_entity?(spec[:elements])
+          return spec[:of] if grape_entity?(spec[:of])
+          return doc_type if grape_entity?(doc_type)
+
+          raw_type
+        end
+
+        def sanitize_type(type)
+          return Constants::SchemaTypes::OBJECT if grape_entity?(type)
+
+          resolve_schema_type(type)
+        end
+
+        def grape_entity?(type)
+          !!resolve_entity_class(type)
+        end
+
+        # Checks if type is a Grape typed array notation like "[String]"
+        def typed_array?(type)
+          type.is_a?(String) && type.match?(TYPED_ARRAY_PATTERN)
+        end
+
+        # Checks if type is a simple Array (class or string)
+        def simple_array?(type)
+          type == Array || type.to_s == "Array"
+        end
+
+        # Builds schema for Grape's typed array notation like "[String]", "[Integer]"
+        def build_typed_array_schema(type)
+          member_type = extract_typed_array_member(type)
+          items_type = resolve_schema_type(member_type)
+          ApiModel::Schema.new(
+            type: Constants::SchemaTypes::ARRAY,
+            items: ApiModel::Schema.new(type: items_type),
+          )
+        end
+
+        def resolve_entity_class(type)
+          return nil unless defined?(Grape::Entity)
+          return type if type.is_a?(Class) && type <= Grape::Entity
+          return nil unless type.is_a?(String) || type.is_a?(Symbol)
+
+          const_name = type.to_s
+          return nil unless valid_constant_name?(const_name)
+          return nil unless Object.const_defined?(const_name, false)
+
+          klass = Object.const_get(const_name, false)
+          klass if klass.is_a?(Class) && klass <= Grape::Entity
+        rescue NameError => e
+          warn "[grape-oas] Could not resolve entity constant '#{const_name}': #{e.message}"
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/request_params_support/schema_enhancer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module RequestParamsSupport
+      # Applies enhancements (constraints, format, examples, etc.) to a schema.
+      class SchemaEnhancer
+        # Applies all enhancements to a schema based on spec and documentation.
+        #
+        # @param schema [ApiModel::Schema] the schema to enhance
+        # @param spec [Hash] the parameter specification
+        # @param doc [Hash] the documentation hash
+        def self.apply(schema, spec, doc)
+          nullable = extract_nullable(spec, doc)
+
+          schema.description ||= doc[:desc]
+          schema.nullable = nullable if schema.respond_to?(:nullable=)
+
+          apply_additional_properties(schema, doc)
+          apply_format_and_example(schema, doc)
+          apply_constraints(schema, doc)
+          apply_values(schema, spec)
+        end
+
+        # Extracts nullable flag from spec and documentation.
+        #
+        # @param spec [Hash] the parameter specification
+        # @param doc [Hash] the documentation hash
+        # @return [Boolean] true if nullable
+        def self.extract_nullable(spec, doc)
+          spec[:allow_nil] || spec[:nullable] || doc[:nullable] || false
+        end
+
+        class << self
+          private
+
+          def apply_additional_properties(schema, doc)
+            if doc.key?(:additional_properties) && schema.respond_to?(:additional_properties=)
+              schema.additional_properties = doc[:additional_properties]
+            end
+            if doc.key?(:unevaluated_properties) && schema.respond_to?(:unevaluated_properties=)
+              schema.unevaluated_properties = doc[:unevaluated_properties]
+            end
+            defs = extract_defs(doc)
+            schema.defs = defs if defs.is_a?(Hash) && schema.respond_to?(:defs=)
+          end
+
+          def apply_format_and_example(schema, doc)
+            schema.format = doc[:format] if doc[:format] && schema.respond_to?(:format=)
+            schema.examples = doc[:example] if doc[:example] && schema.respond_to?(:examples=)
+          end
+
+          def apply_constraints(schema, doc)
+            schema.minimum = doc[:minimum] if doc.key?(:minimum) && schema.respond_to?(:minimum=)
+            schema.maximum = doc[:maximum] if doc.key?(:maximum) && schema.respond_to?(:maximum=)
+            schema.min_length = doc[:min_length] if doc.key?(:min_length) && schema.respond_to?(:min_length=)
+            schema.max_length = doc[:max_length] if doc.key?(:max_length) && schema.respond_to?(:max_length=)
+            schema.pattern = doc[:pattern] if doc.key?(:pattern) && schema.respond_to?(:pattern=)
+          end
+
+          # Applies values from spec[:values] - converts Range to min/max,
+          # evaluates Proc (arity 0), and sets enum for arrays.
+          # Skips Proc/Lambda validators (arity > 0) used for custom validation.
+          def apply_values(schema, spec)
+            values = spec[:values]
+            return unless values
+
+            # Handle Hash format { value: ..., message: ... } - extract the value
+            values = values[:value] if values.is_a?(Hash) && values.key?(:value)
+
+            # Handle Proc/Lambda
+            if values.respond_to?(:call)
+              # Skip validators (arity > 0) - they validate individual values
+              return if values.arity != 0
+
+              # Evaluate arity-0 procs - they return enum arrays
+              values = values.call
+            end
+
+            if values.is_a?(Range)
+              apply_range_values(schema, values)
+            elsif values.is_a?(Array) && values.any?
+              schema.enum = values if schema.respond_to?(:enum=)
+            end
+          end
+
+          # Converts a Range to minimum/maximum constraints.
+          # For numeric ranges (Integer, Float), uses min/max.
+          # For other ranges (e.g., 'a'..'z'), expands to enum array.
+          # Handles endless/beginless ranges (e.g., 1.., ..10).
+          def apply_range_values(schema, range)
+            first_val = range.begin
+            last_val = range.end
+
+            if first_val.is_a?(Numeric) || last_val.is_a?(Numeric)
+              schema.minimum = first_val if first_val && schema.respond_to?(:minimum=)
+              schema.maximum = last_val if last_val && schema.respond_to?(:maximum=)
+            elsif first_val && last_val && schema.respond_to?(:enum=)
+              # Non-numeric bounded range (e.g., 'a'..'z') - expand to enum
+              schema.enum = range.to_a
+            end
+          end
+
+          def extract_defs(doc)
+            doc[:defs] || doc[:$defs]
+          end
+        end
+      end
+    end
+  end
+end