grape-oas 1.4.0 → 1.5.0

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,8 +20,8 @@ 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?("[") }
@@ -152,6 +158,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

@@ -147,7 +147,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_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)

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

@@ -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

@@ -65,6 +65,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 +172,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 +194,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 +203,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 +262,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 +315,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/constants.rb

@@ -12,6 +12,7 @@ module GrapeOAS
       OBJECT = "object"
       ARRAY = "array"
       FILE = "file"
+      NULL = "null"
 
       ALL = [STRING, INTEGER, NUMBER, BOOLEAN, OBJECT, ARRAY, FILE].freeze
     end
@@ -45,6 +46,11 @@ module GrapeOAS
       TYPE_ARRAY = :type_array
       # OAS 2.0: emits `"x-nullable": true` extension
       EXTENSION = :extension
+
+      # Version-specific defaults used by exporters
+      OAS2_DEFAULT = EXTENSION
+      OAS3_DEFAULT = KEYWORD
+      OAS31_DEFAULT = TYPE_ARRAY
     end
 
     # Maximum number of elements to expand from a non-numeric Range into an enum array.
@@ -52,12 +58,18 @@ module GrapeOAS
     MAX_ENUM_RANGE_SIZE = 100
 
     # Regex patterns for Grape's stringified type notations.
-    # Grape converts `type: [SomeClass]` to "[SomeClass]" and
-    # `type: [String, Integer]` to "[String, Integer]" for documentation.
+    # Grape's ParamsDocumentation TypeCache stores `coerce_type.to_s`:
+    # - `type: [SomeClass]` / `type: Array[SomeClass]` → "[SomeClass]" (Array#to_s)
+    # - `types: [String, Integer]` → "[String, Integer]" (Array#to_s of the types list)
+    # - Grape 3.3+ `type: Array[Integer, String]` → "Array[Integer, String]"
+    #   (VariantCollectionCoercer#to_s, grape#2758). Distinct from the `types:`
+    #   form so a collection of variant members is not confused with a scalar
+    #   that accepts multiple types. `Set[...]` is the same for Set containers.
     module TypePatterns
       CONST_NAME = /(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*/
-      TYPED_ARRAY = /\A\[(?<inner>#{CONST_NAME})\]\z/
+      TYPED_ARRAY = /\A(?:(?<container>Array|Set))?\[(?<inner>#{CONST_NAME})\]\z/
       MULTI_TYPE = /\A\[(#{CONST_NAME}(?:,\s*#{CONST_NAME})+)\]\z/
+      VARIANT_COLLECTION = /\A(?<container>Array|Set)\[(?<inner>#{CONST_NAME}(?:,\s*#{CONST_NAME})+)\]\z/
     end
 
     # Default values for OpenAPI spec when not provided by user
@@ -95,7 +107,7 @@ module GrapeOAS
       "float" => { type: SchemaTypes::NUMBER, format: "float" },
       "bigdecimal" => { type: SchemaTypes::NUMBER, format: "double" },
       "string" => { type: SchemaTypes::STRING },
-      "integer" => { type: SchemaTypes::INTEGER, format: "int32" },
+      "integer" => { type: SchemaTypes::INTEGER },
       "number" => { type: SchemaTypes::NUMBER, format: "double" },
       "boolean" => { type: SchemaTypes::BOOLEAN },
       "grape::api::boolean" => { type: SchemaTypes::BOOLEAN },

data/lib/grape_oas/documentation_extension.rb

@@ -3,9 +3,7 @@
 module GrapeOAS
   module DocumentationExtension
     # Primary entry for grape-oas documentation
-    def add_oas_documentation(**options)
-      return if options.delete(:hide_documentation_path)
-
+    def add_oas_documentation(hide_documentation_path: true, **options)
       # Prefer grape-oas namespaced options to avoid clashing with grape-swagger
       default_mount_path = options.delete(:oas_mount_path) ||
                            options.delete(:mount_path) ||
@@ -25,13 +23,13 @@ module GrapeOAS
       api = self
 
       mount_paths.each do |key, path|
-        add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api)
+        add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api, hidden: hide_documentation_path)
       end
     end
 
-    def add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api)
+    def add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api, hidden: false)
       # Main route without namespace filter
-      add_route(path) do
+      add_route(path, hidden: hidden) do
         GrapeOAS::DocumentationExtension.generate_documentation(
           self, api, key, default_format, cache_control, etag_value, options, nil,
         )
@@ -39,7 +37,7 @@ module GrapeOAS
 
       # Route with namespace filter: /swagger_doc/:namespace
       # Supports nested namespaces via *namespace (catches slashes)
-      add_route("#{path}/*namespace") do
+      add_route("#{path}/*namespace", hidden: hidden) do
         namespace_filter = params[:namespace]&.sub(/\.json$/, "")
         GrapeOAS::DocumentationExtension.generate_documentation(
           self, api, key, default_format, cache_control, etag_value, options, namespace_filter,
@@ -89,10 +87,10 @@ module GrapeOAS
     private
 
     # Minimal route mounting helper
-    def add_route(path, &block)
+    def add_route(path, hidden: false, &block)
       api_class = self
       namespace do
-        get(path) { instance_exec(api_class, &block) }
+        get(path, hidden: hidden) { instance_exec(api_class, &block) }
       end
     end
 

data/lib/grape_oas/exporter/concerns/schema_indexer.rb

@@ -47,10 +47,21 @@ module GrapeOAS
           end
         end
 
-        def index_schema(schema, index)
-          return unless schema.respond_to?(:canonical_name) && schema.canonical_name
+        def index_schema(schema, index, seen = Set.new)
+          return unless schema
+
+          schema_id = schema.object_id
+          return if seen.include?(schema_id)
 
-          index[schema.canonical_name] ||= schema
+          seen << schema_id
+          index[schema.canonical_name] ||= schema if schema.respond_to?(:canonical_name) && schema.canonical_name
+          index_schema(schema.items, index, seen) if schema.respond_to?(:items) && schema.items
+          schema.properties.each_value { |child| index_schema(child, index, seen) } if schema.respond_to?(:properties) && schema.properties
+          %i[all_of one_of any_of].each do |composition|
+            next unless schema.respond_to?(composition)
+
+            Array(schema.public_send(composition)).each { |child| index_schema(child, index, seen) }
+          end
         end
 
         def collect_refs(schema, pending, seen = Set.new)

data/lib/grape_oas/exporter/oas2/operation.rb

@@ -15,8 +15,10 @@ module GrapeOAS
           {
             "consumes" => consumes,
             "produces" => produces,
-            "parameters" => Parameter.new(@op, @ref_tracker, nullable_strategy: strategy).build,
-            "responses" => Response.new(@op.responses, @ref_tracker, nullable_strategy: strategy).build
+            "parameters" => Parameter.new(@op, @ref_tracker, nullable_strategy: strategy,
+                                                             composition_extensions: @options[:composition_extensions],).build,
+            "responses" => Response.new(@op.responses, @ref_tracker, nullable_strategy: strategy,
+                                                                     composition_extensions: @options[:composition_extensions],).build
           }
         end
 

data/lib/grape_oas/exporter/oas2/parameter.rb

@@ -5,7 +5,7 @@ module GrapeOAS
     module OAS2
       class Parameter
         PRIMITIVE_MAPPINGS = {
-          Constants::SchemaTypes::INTEGER => { type: Constants::SchemaTypes::INTEGER, format: "int32" },
+          Constants::SchemaTypes::INTEGER => { type: Constants::SchemaTypes::INTEGER },
           "long" => { type: Constants::SchemaTypes::INTEGER, format: "int64" },
           "float" => { type: Constants::SchemaTypes::NUMBER, format: "float" },
           "double" => { type: Constants::SchemaTypes::NUMBER, format: "double" },
@@ -18,15 +18,24 @@ module GrapeOAS
           "uuid" => { type: Constants::SchemaTypes::STRING, format: "uuid" }
         }.freeze
 
-        def initialize(operation, ref_tracker = nil, nullable_strategy: nil)
+        def initialize(operation, ref_tracker = nil, nullable_strategy: nil, composition_extensions: false)
           @op = operation
           @ref_tracker = ref_tracker
           @nullable_strategy = nullable_strategy
+          @composition_extensions = composition_extensions
         end
 
+        FORM_MEDIA_TYPES = %w[application/x-www-form-urlencoded multipart/form-data].freeze
+
         def build
           params = Array(@op.parameters).map { |param| build_parameter(param) }
-          params << build_body_parameter(@op.request_body) if @op.request_body
+          if @op.request_body
+            if form_only_request?
+              params.concat(build_form_parameters(@op.request_body))
+            else
+              params << build_body_parameter(@op.request_body)
+            end
+          end
           params
         end
 
@@ -76,6 +85,7 @@ module GrapeOAS
           result["maxLength"] = schema.max_length if schema.respond_to?(:max_length) && !schema.max_length.nil?
           result["minItems"] = schema.min_items if schema.respond_to?(:min_items) && !schema.min_items.nil?
           result["maxItems"] = schema.max_items if schema.respond_to?(:max_items) && !schema.max_items.nil?
+          result["uniqueItems"] = true if schema.respond_to?(:unique_items) && schema.unique_items
           result["pattern"] = schema.pattern if schema.respond_to?(:pattern) && schema.pattern
           result["enum"] = normalize_enum(schema.enum, result["type"]) if schema.respond_to?(:enum) && schema.enum
           result["default"] = schema.default if schema.respond_to?(:default) && !schema.default.nil?
@@ -84,15 +94,18 @@ module GrapeOAS
         def normalize_enum(enum_vals, type)
           return nil unless enum_vals.is_a?(Array)
 
-          coerced = enum_vals.map do |v|
-            case type
-            when Constants::SchemaTypes::INTEGER then v.to_i if v.respond_to?(:to_i)
-            when Constants::SchemaTypes::NUMBER then v.to_f if v.respond_to?(:to_f)
-            else v
-            end
-          end.compact
+          result = enum_vals.each_with_object([]) do |v, acc|
+            next if v.nil?
+
+            coerced_v = case type
+                        when Constants::SchemaTypes::INTEGER then v.to_i if v.respond_to?(:to_i)
+                        when Constants::SchemaTypes::NUMBER then v.to_f if v.respond_to?(:to_f)
+                        else v
+                        end
+            acc << coerced_v unless coerced_v.nil?
+          end
 
-          result = coerced.uniq
+          result.uniq!
           return nil if result.empty?
 
           result
@@ -100,12 +113,58 @@ module GrapeOAS
 
         def apply_collection_format(result, param, type)
           return unless type == Constants::SchemaTypes::ARRAY
+
+          result["items"] = build_schema_or_ref(param.schema.items) if param.schema.items
           return unless param.collection_format
 
           valid_formats = %w[csv ssv tsv pipes multi brackets]
           result["collectionFormat"] = param.collection_format if valid_formats.include?(param.collection_format)
         end
 
+        def form_only_request?
+          consumes = Array(@op.consumes)
+          consumes.any? && consumes.all? { |mime| FORM_MEDIA_TYPES.include?(mime) }
+        end
+
+        def build_form_parameters(request_body)
+          schema = Array(request_body.media_types).first&.schema
+          return [] unless schema
+
+          unless [nil, "object"].include?(schema.type) && !composition?(schema)
+            raise ArgumentError, "OAS2 form bodies must have object properties; use OAS3 for this request schema"
+          end
+
+          required = Array(schema.required).map(&:to_s)
+          schema.properties.map do |name, property_schema|
+            unless form_property?(property_schema)
+              raise ArgumentError, "OAS2 cannot represent form field #{name.inspect}; use OAS3 for complex form fields"
+            end
+
+            build_parameter(
+              ApiModel::Parameter.new(
+                name: name.to_s,
+                location: "formData",
+                required: required.include?(name.to_s),
+                description: property_schema.description,
+                schema: property_schema,
+              ),
+            )
+          end
+        end
+
+        def form_property?(schema, array_item: false)
+          return false unless schema && !composition?(schema)
+          return false if array_item && schema.canonical_name
+          return form_property?(schema.items, array_item: true) if schema.type == "array"
+
+          types = array_item ? %w[string integer number boolean] : %w[string integer number boolean file]
+          types.include?(schema.type)
+        end
+
+        def composition?(schema)
+          schema.all_of&.any? || schema.one_of&.any? || schema.any_of&.any?
+        end
+
         def build_body_parameter(request_body)
           schema = build_body_schema(request_body)
           name = derive_body_name(request_body)
@@ -139,10 +198,11 @@ module GrapeOAS
         def build_schema_or_ref(schema)
           if schema.respond_to?(:canonical_name) && schema.canonical_name
             @ref_tracker << schema.canonical_name if @ref_tracker
-            ref_name = schema.canonical_name.gsub("::", "_")
+            ref_name = GrapeOAS.schema_ref_name.call(schema.canonical_name)
             { "$ref" => "#/definitions/#{ref_name}" }
           else
-            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy,
+                                             composition_extensions: @composition_extensions,).build
           end
         end
       end

data/lib/grape_oas/exporter/oas2/paths.rb

@@ -12,6 +12,7 @@ module GrapeOAS
         def build_operation(operation)
           Operation.new(operation, @ref_tracker,
                         nullable_strategy: @options[:nullable_strategy],
+                        composition_extensions: @options[:composition_extensions],
                         suppress_default_error_response: @options[:suppress_default_error_response],).build
         end
       end

data/lib/grape_oas/exporter/oas2/response.rb

@@ -4,10 +4,11 @@ module GrapeOAS
   module Exporter
     module OAS2
       class Response
-        def initialize(responses, ref_tracker = nil, nullable_strategy: nil)
+        def initialize(responses, ref_tracker = nil, nullable_strategy: nil, composition_extensions: false)
           @responses = responses
           @ref_tracker = ref_tracker
           @nullable_strategy = nullable_strategy
+          @composition_extensions = composition_extensions
         end
 
         def build
@@ -34,10 +35,11 @@ module GrapeOAS
         def build_schema_or_ref(schema)
           if schema.respond_to?(:canonical_name) && schema.canonical_name
             @ref_tracker << schema.canonical_name if @ref_tracker
-            ref_name = schema.canonical_name.gsub("::", "_")
+            ref_name = GrapeOAS.schema_ref_name.call(schema.canonical_name)
             { "$ref" => "#/definitions/#{ref_name}" }
           else
-            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy,
+                                             composition_extensions: @composition_extensions,).build
           end
         end
 
@@ -60,7 +62,7 @@ module GrapeOAS
         end
 
         def build_examples(media_types, response_examples = nil)
-          return nil unless media_types
+          return nil if media_types.nil? || media_types.empty?
 
           mt = Array(media_types).first
           # Media type examples take precedence over response-level examples