grape-oas 1.4.0 → 1.5.1

data/lib/grape_oas/api_model_builders/request_params.rb

@@ -3,7 +3,13 @@
 module GrapeOAS
   module ApiModelBuilders
     class RequestParams
-      ROUTE_PARAM_REGEX = /(?<=:)\w+/
+      include Concerns::RouteValidations
+
+      ROUTE_PARAM_REGEX = /(?<=[:*])\w+/
+
+      def self.path_param_names(path)
+        path.sub(/(\(\.[^)]+\))+$/, "").scan(ROUTE_PARAM_REGEX)
+      end
 
       attr_reader :api, :route, :path_param_name_map
 
@@ -14,29 +20,43 @@ module GrapeOAS
       end
 
       def build
-        route_params = route.path.scan(ROUTE_PARAM_REGEX)
-        all_params = route.options[:params] || {}
+        route_params = self.class.path_param_names(route.path)
+        all_params = declared_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)
+          body_schema, parameters = build_with_nested_params(all_params, route_params)
         else
-          build_flat_params(all_params, route_params)
+          body_schema, parameters = build_flat_params(all_params, route_params)
         end
+
+        [body_schema, parameters]
       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)
+        body_params = nested_body_params(all_params, route_params)
+        body_schema = nested_params_builder.build(body_params, path_params: route_params)
         non_body_params = extract_non_body_params(all_params, route_params)
 
         [body_schema, non_body_params]
       end
 
+      def nested_body_params(all_params, route_params)
+        body_roots = all_params.filter_map do |name, spec|
+          next if name.include?("[")
+
+          location = location_resolver.resolve(name: name, spec: spec, route_params: route_params, route: route)
+          name if location == "body"
+        end.to_set
+
+        all_params.select { |name, _spec| body_roots.include?(name.split("[", 2).first) }
+      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)
@@ -66,33 +86,38 @@ module GrapeOAS
       end
 
       # Extracts non-body params (path, query, header) from flat params.
-      # For non-body HTTP methods (GET, HEAD, DELETE), also includes nested params
-      # as flat query parameters with bracket notation (e.g., "tax_id[type]"),
-      # unless request_body is explicitly enabled.
+      # Nested params (bracket notation, e.g. "tax_id[type]") are included as
+      # flat non-body parameters, taking their parent's resolved location,
+      # regardless of HTTP method — a nested Hash explicitly documented
+      # `in: "header"` on a write route (POST/PUT/PATCH) still belongs in
+      # the header, not the body.
       def extract_non_body_params(all_params, route_params)
         params = []
-        http_method = route.request_method.to_s.downcase
-        flatten_nested = should_flatten_nested_to_query?(http_method, all_params)
 
         all_params.each do |name, spec|
           # Skip hidden params
           next if location_resolver.hidden_parameter?(spec)
 
-          is_nested = name.include?("[")
-          is_hash_param = location_resolver.body_param?(spec)
+          if name.include?("[")
+            root = name.split("[", 2).first
+            root_spec = all_params[root] || {}
+            next if location_resolver.hidden_parameter?(root_spec)
 
-          # For nested bracket params (e.g., "tax_id[type]"), include as query params
-          # for non-body HTTP methods (unless request_body is explicitly enabled)
-          if is_nested
-            next unless flatten_nested
+            root_location = location_resolver.resolve(name: root, spec: root_spec, route_params: route_params, route: route)
+            next if root_location == "body"
+            # A Hash root can itself be a real route capture (e.g. ":filter"),
+            # but that doesn't make its bracket children path segments too —
+            # only the root itself matches the URL template.
+            next if root_location == "path"
 
-            params << build_parameter(name, "query", spec[:required] || false, schema_builder.build(spec), spec)
+            params << build_parameter(name, root_location, spec[:required] || false, schema_builder.build(spec), spec)
             next
           end
 
-          # Skip Hash type params (they're handled via nested bracket params above
-          # or via body schema for POST/PUT/PATCH)
-          next if is_hash_param
+          # Skip Hash type params with nested children of their own (they're
+          # handled via the nested bracket branch above or via body schema).
+          # A childless Hash falls through to the generic path below.
+          next if location_resolver.hash_param?(spec) && all_params.keys.any? { |k| k.start_with?("#{name}[") }
 
           location = location_resolver.resolve(
             name: name,
@@ -109,28 +134,6 @@ module GrapeOAS
         params
       end
 
-      # Determines whether nested params should be flattened to query params.
-      # Returns true for GET/HEAD/DELETE unless body is explicitly requested via:
-      # - route-level `request_body: true` option
-      # - any parameter with `documentation: { in: 'body' }` or `documentation: { param_type: 'body' }`
-      def should_flatten_nested_to_query?(http_method, all_params)
-        return false unless Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method)
-
-        # If request_body is explicitly enabled at route level, use body schema
-        return false if route.options.dig(:documentation, :request_body) || route.options[:request_body]
-
-        # If any parameter is explicitly marked as body, use body schema
-        has_explicit_body_param = all_params.any? do |name, spec|
-          next false if name.include?("[") # Skip bracket params, check parent Hash params only
-
-          param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
-          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
-          param_type == "body" || in_location == "body"
-        end
-
-        !has_explicit_body_param
-      end
-
       def build_parameter(name, location, required, schema, spec)
         doc = spec[:documentation] || {}
         style = doc.fetch(:style) { doc["style"] }
@@ -139,7 +142,7 @@ module GrapeOAS
         ApiModel::Parameter.new(
           location: location,
           name: name,
-          required: required,
+          required: location == "path" || required,
           schema: schema,
           description: spec[:documentation]&.dig(:desc) || spec[:desc],
           collection_format: extract_collection_format(spec),
@@ -152,6 +155,80 @@ module GrapeOAS
         spec.dig(:documentation, :collectionFormat) || spec.dig(:documentation, :collection_format)
       end
 
+      # Grape 3.x stores documented params in `route.options[:params]`.
+      # Grape 4.0 moved them to `Route#params` (grape#2785) and no longer
+      # copies the hash into options. Path captures that are not Hash specs
+      # (empty-string defaults from the pattern) are dropped.
+      def declared_params
+        specs = params_from_options || params_from_route
+        return {} unless specs.is_a?(Hash)
+
+        flat = specs.select { |_name, spec| spec.is_a?(Hash) }
+        conditional = conditional_param_names
+        return flat if conditional.empty?
+
+        flat.each_with_object({}) do |(name, spec), params|
+          params[name] = conditional.include?(name.to_s) ? spec.merge(required: false) : spec
+        end
+      end
+
+      # Returns names of params that Grape will only validate conditionally
+      # (declared inside a `given` block). Their validators have a
+      # `params_scope` with `@dependent_on` set.
+      def conditional_param_names
+        return Set.new unless route.respond_to?(:app) && route.app.respond_to?(:inheritable_setting)
+
+        validations = grape_route_validations(route.app.inheritable_setting)
+        return Set.new unless validations.is_a?(Array)
+
+        conditional = Set.new
+        unconditional = Set.new
+        validations.each do |validator|
+          scope, attrs = validator_details(validator)
+          next unless scope.respond_to?(:full_name)
+
+          target = conditional_scope?(scope) ? conditional : unconditional
+          Array(attrs).each { |attr| target << scope.full_name(attr) }
+        end
+        conditional - unconditional
+      end
+
+      # Grape < 3.2 stores validators as hashes; >= 3.2 stores instances.
+      def validator_details(validator)
+        presence = Grape::Validations::Validators::PresenceValidator
+        if validator.is_a?(Hash)
+          return unless validator[:validator_class].is_a?(Class) && validator[:validator_class] <= presence
+
+          [validator[:params_scope], validator[:attributes]]
+        elsif validator.is_a?(presence)
+          [validator.instance_variable_get(:@scope), validator.attrs]
+        end
+      end
+
+      def conditional_scope?(scope)
+        while scope
+          return true if scope.instance_variable_get(:@dependent_on)&.any?
+
+          scope = scope.respond_to?(:parent) ? scope.parent : nil
+        end
+        false
+      end
+
+      def params_from_options
+        params = route.options[:params]
+        params if params.is_a?(Hash) && params.any?
+      end
+
+      def params_from_route
+        return unless route.respond_to?(:params)
+        # Grape 3.x Route#params(input = nil) merges path captures; skip it.
+        # Grape 4.0 Route#params takes no arguments and is the documentation hash.
+        return unless route.method(:params).arity.zero?
+
+        params = route.params
+        params if params.is_a?(Hash) && params.any?
+      end
+
       def location_resolver
         RequestParamsSupport::ParamLocationResolver
       end

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

@@ -30,7 +30,6 @@ module GrapeOAS
 
           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)
@@ -147,7 +146,7 @@ module GrapeOAS
           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]
+          schema.examples = doc[:example] if doc.key?(:example)
           nullable = SchemaEnhancer.extract_nullable(doc)
           schema.nullable = (schema.nullable || nullable) if schema.respond_to?(:nullable=)
         end

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

@@ -5,6 +5,12 @@ module GrapeOAS
     module RequestParamsSupport
       # Resolves the location (path, query, body, header) for a parameter.
       class ParamLocationResolver
+        # Locations `param_type:`/`in:` may explicitly name. An unrecognized
+        # value (a typo, or a grape-swagger location this library doesn't
+        # resolve to, like `formData`) is treated as unset rather than
+        # emitted verbatim, since nothing downstream validates `Parameter#location`.
+        VALID_EXPLICIT_LOCATIONS = %w[body query header path cookie].freeze
+
         # Determines the location for a parameter.
         #
         # @param name [String] the parameter name
@@ -18,29 +24,14 @@ module GrapeOAS
           extract_from_spec(spec, route)
         end
 
-        # Checks if a parameter should be in the request body.
-        # Supports both `param_type: 'body'` and `in: 'body'` for grape-swagger compatibility.
-        #
-        # @param spec [Hash] the parameter specification
-        # @return [Boolean] true if it's a body parameter
-        def self.body_param?(spec)
-          param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
-          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
-
-          param_type == "body" || in_location == "body" || [Hash, "Hash"].include?(spec[:type])
-        end
-
-        # Checks if a parameter is explicitly marked as NOT a body param.
-        # Supports both `param_type` and `in` for grape-swagger compatibility.
+        # Checks if a parameter is a Hash type. Hash parents are represented
+        # by their children (nested params) or the request body, never
+        # themselves as a parameter.
         #
         # @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
-          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
-          location = param_type || in_location
-
-          location && %w[query header path].include?(location)
+        # @return [Boolean] true if the parameter type is Hash
+        def self.hash_param?(spec)
+          [Hash, "Hash"].include?(spec[:type])
         end
 
         # Checks if a parameter should be hidden from documentation.
@@ -56,6 +47,10 @@ module GrapeOAS
           hidden
         end
 
+        def self.route_body_opted_in?(route)
+          !!(route.options[:body_name] || route.options.dig(:documentation, :request_body) || route.options[:request_body])
+        end
+
         class << self
           private
 
@@ -70,24 +65,35 @@ module GrapeOAS
           # Note: If both `param_type` and `in` are specified, `param_type` takes precedence.
           # For example, `{ param_type: 'query', in: 'body' }` will be treated as query.
           #
+          # `resolve` already returns "path" for an actual route capture before
+          # calling this method, so an explicit `in: "path"` / `param_type: "path"`
+          # reaching here is always a mismatch (the name can never appear in the
+          # URL template) and is ignored, same as an unrecognized location.
+          #
           # @param spec [Hash] the parameter specification
           # @param route [Object] the Grape route object
           # @return [String] the parameter location
           def extract_from_spec(spec, route)
-            # If body_name is set on the route, treat non-path params as body by default
-            param_type = spec.dig(:documentation, :param_type)
-            in_location = spec.dig(:documentation, :in)
-            return "body" if route.options[:body_name] && !param_type && !in_location
+            location = explicit_location(spec)
+            location = nil if location == "path"
+            return "body" if route_body_opted_in?(route) && location.nil?
 
             # Support both param_type and in for grape-swagger compatibility
             # param_type takes precedence over in when both are specified
-            explicit_location = (param_type || in_location)&.to_s&.downcase
-            return explicit_location if explicit_location
+            return location if location
 
             # Default: body for write methods (POST/PUT/PATCH), query for read methods (GET/DELETE/HEAD)
             http_method = route.request_method.to_s.downcase
             Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method) ? "query" : "body"
           end
+
+          def explicit_location(spec)
+            doc = spec[:documentation] || {}
+            param_type = doc[:param_type] || doc["param_type"]
+            in_location = doc[:in] || doc["in"]
+            location = (param_type || in_location)&.to_s&.downcase
+            location if VALID_EXPLICIT_LOCATIONS.include?(location)
+          end
         end
       end
     end

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

@@ -36,7 +36,7 @@ module GrapeOAS
 
           # is_array: true on a typed array like "[String]" is redundant and would
           # double-wrap it as Array<Array<...>> via build_primitive_array_schema.
-          return GrapeOAS.type_resolvers.build_schema(raw_type) if doc[:is_array] && extract_typed_array_member(raw_type)
+          return GrapeOAS.type_resolvers.build_schema(raw_type) if doc[:is_array] && TypeResolvers::ArrayResolver.handles?(raw_type)
           return build_primitive_array_schema(doc_type, raw_type) if doc[:is_array]
           return build_entity_schema(doc_type) if grape_entity?(doc_type)
           return build_entity_schema(raw_type) if grape_entity?(raw_type)
@@ -119,19 +119,17 @@ module GrapeOAS
           type_names = extract_multi_types(type)
 
           # OPTIMIZE: [Type, Nil] becomes nullable Type instead of oneOf
-          if nullable_type_pair?(type_names)
-            non_nil_type = type_names.find { |t| !nil_type_name?(t) }
+          if (nullable_type = Constants.nullable_type(type_names))
             return ApiModel::Schema.new(
-              type: resolve_schema_type(non_nil_type),
-              format: Constants.format_for_type(non_nil_type),
+              type: resolve_schema_type(nullable_type),
+              format: Constants.format_for_type(nullable_type),
               nullable: true,
             )
           end
 
           # General case: build oneOf schema
           # Filter out nil types - OpenAPI 3.0 uses nullable property instead
-          has_nil_type = type_names.any? { |t| nil_type_name?(t) }
-          non_nil_types = type_names.reject { |t| nil_type_name?(t) }
+          nil_types, non_nil_types = type_names.partition { |type_name| Constants.nil_type?(type_name) }
 
           schemas = non_nil_types.map do |type_name|
             ApiModel::Schema.new(
@@ -139,26 +137,9 @@ module GrapeOAS
               format: Constants.format_for_type(type_name),
             )
           end
-          ApiModel::Schema.new(one_of: schemas, nullable: has_nil_type ? true : nil)
-        end
-
-        # Checks if type_names is a pair of [SomeType, NilType]
-        def nullable_type_pair?(type_names)
-          return false unless type_names.size == 2
-
-          type_names.one? { |t| nil_type_name?(t) }
-        end
-
-        # Checks if the type name represents a nil/null type
-        def nil_type_name?(type_name)
-          normalized = type_name.to_s
-          # Match common nil type patterns:
-          # - "NilClass" (Ruby's nil type)
-          # - "Nil" (shorthand)
-          # - "Foo::Nil", "Types::Nil" (namespaced nil types)
-          normalized == "NilClass" ||
-            normalized == "Nil" ||
-            normalized.end_with?("::Nil")
+          schema = ApiModel::Schema.new(one_of: schemas)
+          schema.nullable = true if nil_types.any?
+          schema
         end
 
         def build_primitive_schema(raw_type, doc)

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

@@ -13,7 +13,7 @@ module GrapeOAS
         def self.apply(schema, spec, doc)
           nullable = extract_nullable(doc)
 
-          schema.description ||= doc[:desc]
+          schema.description ||= doc[:desc] || spec[:desc]
           # Preserve existing nullable: true (e.g., from [Type, Nil] optimization)
           schema.nullable = (schema.nullable || nullable) if schema.respond_to?(:nullable=)
 
@@ -24,15 +24,9 @@ module GrapeOAS
           apply_default(schema, spec, doc)
         end
 
-        # Extracts nullable flag from a documentation hash.
-        #
-        # @param doc [Hash] the documentation hash
-        # @return [Boolean] true if nullable
-        def self.extract_nullable(doc)
-          doc[:nullable] || (doc[:x].is_a?(Hash) && doc[:x][:nullable]) || false
-        end
-
         class << self
+          include GrapeOAS::ApiModelBuilders::Concerns::OasUtilities
+
           private
 
           def apply_additional_properties(schema, doc)
@@ -58,7 +52,7 @@ module GrapeOAS
 
           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=)
+            schema.examples = doc[:example] if doc.key?(:example) && schema.respond_to?(:examples=)
           end
 
           def apply_values(schema, spec)

data/lib/grape_oas/api_model_builders/response.rb

@@ -48,7 +48,11 @@ module GrapeOAS
       # Parsers are tried in order of priority
       def response_specs
         parser = parsers.find { |p| p.applicable?(route) }
-        parser ? parser.parse(route) : []
+        return [] unless parser
+
+        parser.parse(route).each do |spec|
+          spec[:code] = ResponseParsers::Base.normalize_status_code(spec[:code])
+        end
       end
 
       def parsers
@@ -65,6 +69,9 @@ module GrapeOAS
       # Else if any spec has `one_of:`, build a oneOf response from one_of entries and
       # any regular specs in the group (this branch only runs when no `as:` entries exist)
       def build_response_from_group(group_specs)
+        first_spec = group_specs.first
+        return build_response_without_content(first_spec) if bodyless_status?(first_spec[:code])
+
         has_one_of = group_specs.any? { |s| s[:one_of] && !s[:one_of].empty? }
         has_as = group_specs.any? { |s| !s[:as].nil? }
 
@@ -169,14 +176,16 @@ module GrapeOAS
 
       # Merges examples from multiple specs
       def merge_examples(specs)
-        examples = specs.map { |s| s[:examples] }.compact
+        examples = specs.filter_map { |s| s[:examples] }
         return nil if examples.empty?
 
         examples.reduce({}, :merge)
       end
 
       def build_response_from_spec(spec)
+        code_str = spec[:code].to_s
         entity_schema = build_schema(spec[:entity])
+        entity_schema = array_schema(entity_schema) if spec[:is_array]
         schema = wrap_with_root(entity_schema, spec[:entity], is_array: spec[:is_array])
         media_types = Array(response_content_types).map do |mime|
           build_media_type(
@@ -189,7 +198,7 @@ module GrapeOAS
         description = message.is_a?(String) ? message : message&.to_s
 
         GrapeOAS::ApiModel::Response.new(
-          http_status: spec[:code].to_s,
+          http_status: code_str,
           description: description || "Success",
           media_types: media_types,
           headers: normalize_headers(spec[:headers]) || headers_from_route,
@@ -198,6 +207,25 @@ module GrapeOAS
         )
       end
 
+      def build_response_without_content(spec)
+        message = spec[:message]
+        description = message.is_a?(String) ? message : message&.to_s
+
+        GrapeOAS::ApiModel::Response.new(
+          http_status: spec[:code].to_s,
+          description: description || "Success",
+          media_types: [],
+          headers: normalize_headers(spec[:headers]) || headers_from_route,
+          extensions: spec[:extensions] || extensions_from_route,
+        )
+      end
+
+      # RFC 9110 §6.4.1 and §15.3.6: these responses never carry a message body.
+      def bodyless_status?(code)
+        status = code.to_s.to_i
+        status.between?(100, 199) || status == 204 || status == 205 || status == 304
+      end
+
       def array_schema(schema)
         GrapeOAS::ApiModel::Schema.new(
           type: Constants::SchemaTypes::ARRAY,
@@ -238,7 +266,7 @@ module GrapeOAS
       # Build schema for response body
       # Delegates to EntityIntrospector when entity is present
       def build_schema(entity_class)
-        return GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::STRING) unless entity_class
+        return GrapeOAS::ApiModel::Schema.new unless entity_class
 
         GrapeOAS.introspectors.build_schema(entity_class, stack: [], registry: {})
       end
@@ -291,7 +319,7 @@ module GrapeOAS
       end
 
       def response_content_types
-        resolve_content_types
+        explicit_media_types(:produces) || resolve_content_types
       end
     end
   end

data/lib/grape_oas/api_model_builders/response_parsers/base.rb

@@ -29,6 +29,17 @@ module GrapeOAS
 
         private
 
+        def normalize_status_code(status)
+          return status unless status.is_a?(Symbol)
+
+          status_name = status.to_s
+          return status_name if status_name == "default" || status_name.match?(/\A[1-5](?:\d{2}|XX)\z/)
+
+          Rack::Utils.status_code(status)
+        end
+
+        module_function :normalize_status_code
+
         # Extract status code from hash, supporting multiple key names
         def extract_status_code(hash, default_code)
           hash[:code] || hash[:status] || hash[:http_status] || default_code

data/lib/grape_oas/api_model_builders/response_parsers/documentation_responses_parser.rb

@@ -17,10 +17,10 @@ module GrapeOAS
           doc_resps = route.options.dig(:documentation, :responses)
           return [] unless doc_resps.is_a?(Hash)
 
-          doc_resps.map do |code, doc|
+          specs = doc_resps.map do |code, doc|
             doc = normalize_hash_keys(doc)
             {
-              code: code,
+              code: normalize_status_code(code),
               message: extract_description(doc),
               headers: doc[:headers],
               entity: extract_entity(doc, route.options[:entity]),
@@ -28,6 +28,9 @@ module GrapeOAS
               examples: doc[:examples]
             }
           end
+          return specs if specs.any? { |spec| spec[:code].to_s == HttpCodesParser::DEFAULT_RESPONSE_CODE }
+
+          specs + HttpCodesParser.new.default_response_specs(route)
         end
       end
     end