grape-oas 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d956b648ef9686c13b90db7a16bba4038bf505ed069634131ade6cac17b3f8bf
-  data.tar.gz: 740148b7d4a9cb0d09675d53465a6e4b798b5c042245070b7de145401ac47820
+  metadata.gz: e5289691e338b77f7408ed384429c297bfcac143962085e4b02edc1b980b35ff
+  data.tar.gz: 1d03adce8e12922b769ce6679013d14cb4e9bb4bc3ceaa2a6d4fdc2a26d34625
 SHA512:
-  metadata.gz: a9e134fc9ad362b0b2aa505d7dcab8b24cf35697356365fda1d0bc20f081893b675811b2205aca46507aeb6da66ea547cee8bb3a01a5c6de301f097bb7990948
-  data.tar.gz: 3a2c13601c299600272d5ff3e5cccb648f658b61b0a3d1a8cf43c66b0bb35cadae8979f74bffd820ec217ccbd18e8eb65b25c28de9f6b4b67a1972914b524f92
+  metadata.gz: 850eee859637b8e5cab7606b8819931c5b59479aeab6247907fde7578c43b613694a0ab7b2ffb24c1530ac1e878982f555810a7afb83b34cf378d2f6b35cc020
+  data.tar.gz: 1298c51a115ec42502e011e50b41ae3b9bf9a553c834c49b7c3b628d285b7e2853ee8251cf55c742766d951f2ecfc525252aee1950a61ffe8fbd064a84550110

data/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [1.3.0] - 2026-03-27
+
+### Added
+
+- [#48](https://github.com/numbata/grape-oas/pull/48): Add configurable `GrapeOAS.logger` for schema generation warnings - [@numbata](https://github.com/numbata).
+- [#43](https://github.com/numbata/grape-oas/pull/43): Bump actions/upload-artifact from 6 to 7 - [@dependabot[bot]](https://github.com/dependabot[bot]).
+- [#51](https://github.com/numbata/grape-oas/pull/51): Add inline nesting exposure support — block-based `expose :key do ... end` now produces inline object schemas with preserved enum values, min/max constraints, and metadata - [@numbata](https://github.com/numbata).
+
+### Changed
+
+- [#52](https://github.com/numbata/grape-oas/pull/52): Extract `SchemaConstraints` — centralizes numeric/string constraint application (min/max, exclusive flags, length, pattern) and adds `exclusive_minimum`/`exclusive_maximum` support - [@numbata](https://github.com/numbata).
+- [#50](https://github.com/numbata/grape-oas/pull/50): Extract `ValuesNormalizer` — consolidates Proc/Set/Hash value normalization into a single module used by both request params and entity exposures - [@numbata](https://github.com/numbata).
+
+### Fixed
+
+- [#55](https://github.com/numbata/grape-oas/pull/55): Preserve enum values on cached entity schemas — dup the shared schema before applying enum instead of silently discarding the constraint; emit a warning naming the entity - [@numbata](https://github.com/numbata).
+- [#56](https://github.com/numbata/grape-oas/pull/56): Make `NestingMerger` depth-cap warning actionable — include property name and depth cap value in the message - [@numbata](https://github.com/numbata).
+- [#50](https://github.com/numbata/grape-oas/pull/50): Fix `[false]` enum silently dropped — `[false].any?` returns `false` in Ruby, causing boolean-only enum constraints to be discarded - [@numbata](https://github.com/numbata).
+
+- [#49](https://github.com/numbata/grape-oas/pull/49): Fix OOM on wide string range expansion in `values:` — replace unbounded `range.to_a` with bounded enumeration; non-numeric ranges on numeric schemas and numeric ranges on non-numeric schemas now warn and are ignored instead of silently producing invalid output - [@numbata](https://github.com/numbata).
+- [#46](https://github.com/numbata/grape-oas/pull/46): Fix `is_array: true` in request param documentation being ignored for primitive types — only entity types were wrapped in array schema - [@numbata](https://github.com/numbata).
+- [#42](https://github.com/numbata/grape-oas/pull/42): Fix array items `description` and `nullable` placement — hoist to outer array schema instead of wrapping `items` in `allOf`; fix `:description` field naming collision in `PropertyExtractor` - [@numbata](https://github.com/numbata).
+- [#44](https://github.com/numbata/grape-oas/pull/44): Fix RuboCop 1.85 offenses - [@numbata](https://github.com/numbata).
+- [#47](https://github.com/numbata/grape-oas/pull/47): Fix duplicate entries in `Schema#required` array when the same property is added multiple times with `required: true` - [@numbata](https://github.com/numbata).
+
+## [1.2.0] - 2026-03-02
+
+### Added
+
+- [#36](https://github.com/numbata/grape-oas/pull/36): Add extensible TypeResolvers for resolving Grape's stringified parameter types to OpenAPI schemas with rich metadata (format, enum, nullable) - [@numbata](https://github.com/numbata).
+- [#37](https://github.com/numbata/grape-oas/pull/37): Replace boolean `nullable_keyword` with configurable `nullable_strategy` - [@numbata](https://github.com/numbata).
+
+### Fixed
+
+- [#41](https://github.com/numbata/grape-oas/pull/41): Fix `Set` enum values being silently dropped and `maybe(Coercible::Integer)` resolving to `string` instead of `integer` - [@numbata](https://github.com/numbata).
+- [#40](https://github.com/numbata/grape-oas/pull/40): Remove dead `spec[:allow_nil]` and `spec[:nullable]` checks from `extract_nullable` — these values were never set by Grape or grape-swagger - [@numbata](https://github.com/numbata).
+- [#39](https://github.com/numbata/grape-oas/pull/39): Support `documentation: { x: { nullable: true } }` on nested Hash params — nullable flag was ignored for object container schemas - [@numbata](https://github.com/numbata).
+- [#38](https://github.com/numbata/grape-oas/pull/38): Wrap `$ref` in `allOf` when `description` or `nullable` is present — fixes sibling properties being ignored per OpenAPI spec - [@numbata](https://github.com/numbata).
+- [#37](https://github.com/numbata/grape-oas/pull/37): Fix OAS 3.0 `nullable` keyword being constructed but not emitted in the generated output - [@numbata](https://github.com/numbata).
+
 ## [1.1.0] - 2026-01-23
 
 ### Added

data/README.md

@@ -150,6 +150,12 @@ class Entity::User < Grape::Entity
   expose :id, documentation: { type: Integer }
   expose :name, documentation: { type: String }
   expose :posts, using: Entity::Post, documentation: { is_array: true }
+
+  # Block-based nesting produces an inline object schema
+  expose :meta do
+    expose :role, documentation: { type: String, values: %w[admin user guest] }
+    expose :verified, documentation: { type: 'Boolean' }
+  end
 end
 ```
 

data/lib/grape_oas/api_model/api.rb

@@ -11,7 +11,7 @@ module GrapeOAS
     class API < Node
       attr_accessor :title, :version, :paths, :servers, :tag_defs, :components,
                     :host, :base_path, :schemes, :security_definitions, :security,
-                    :registered_schemas, :suppress_default_error_response
+                    :registered_schemas, :suppress_default_error_response, :nullable_strategy
 
       def initialize(title:, version:)
         super()
@@ -28,6 +28,7 @@ module GrapeOAS
         @security = []
         @registered_schemas = []
         @suppress_default_error_response = false
+        @nullable_strategy = nil
       end
 
       def add_path(path)

data/lib/grape_oas/api_model/schema.rb

@@ -51,10 +51,25 @@ module GrapeOAS
       end
 
       def add_property(name, schema, required: false)
-        @properties[name.to_s] = schema
-        @required << name.to_s if required
+        key = name.to_s
+        @properties[key] = schema
+        @required << key if required && !@required.include?(key)
         schema
       end
+
+      protected
+
+      # Ensure dup produces an independent copy — without this, the shallow
+      # copy shares @properties, @required, and @defs with the original.
+      # Property values are duped one level deep (via transform_values(&:dup)),
+      # which triggers initialize_copy recursively on each nested Schema,
+      # producing a full deep copy of the property tree.
+      def initialize_copy(source)
+        super
+        @properties = source.properties.transform_values(&:dup)
+        @required   = source.required.dup
+        @defs       = source.defs.dup
+      end
     end
   end
 end

data/lib/grape_oas/api_model_builder.rb

@@ -19,6 +19,7 @@ module GrapeOAS
       @api.servers = build_servers(options)
       @api.registered_schemas = build_registered_schemas(options[:models])
       @api.suppress_default_error_response = options[:suppress_default_error_response] || false
+      @api.nullable_strategy = options[:nullable_strategy]
 
       @namespace_filter = options[:namespace]
       @apis = []

data/lib/grape_oas/api_model_builders/concerns/type_resolver.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
-require "bigdecimal"
+begin
+  require "bigdecimal"
+rescue LoadError
+  # BigDecimal is an optional default gem dependency.
+end
 
 module GrapeOAS
   module ApiModelBuilders
@@ -8,11 +12,11 @@ module GrapeOAS
       # Centralizes Ruby type to OpenAPI schema type resolution.
       # Used by request builders and introspectors to avoid duplicated type switching logic.
       module TypeResolver
-        # Regex to match Grape's typed array notation like "[String]", "[Integer]"
-        TYPED_ARRAY_PATTERN = /^\[(\w+)\]$/
+        # Regex to match Grape's typed array notation like "[String]", "[Integer]", "[MyModule::MyType]"
+        TYPED_ARRAY_PATTERN = /\A\[(\w+(?:::\w+)*)\]\z/
 
         # Regex to match Grape's multi-type notation like "[String, Integer]", "[String, Float]"
-        MULTI_TYPE_PATTERN = /^\[(\w+(?:::\w+)*(?:,\s*\w+(?:::\w+)*)+)\]$/
+        MULTI_TYPE_PATTERN = /\A\[(\w+(?:::\w+)*(?:,\s*\w+(?:::\w+)*)+)\]\z/
 
         # Resolves a Ruby class or type name to its OpenAPI schema type string.
         # Handles both Ruby classes (Integer, Float) and string type names ("integer", "float").
@@ -27,7 +31,8 @@ module GrapeOAS
           # Handle Ruby classes directly
           if type.is_a?(Class)
             # Check static mapping first
-            return Constants::RUBY_TYPE_MAPPING[type] if Constants::RUBY_TYPE_MAPPING.key?(type)
+            mapped = Constants::RUBY_TYPE_MAPPING[type]
+            return mapped if mapped
 
             # Handle Grape::API::Boolean dynamically (may not be loaded at constant definition time)
             return Constants::SchemaTypes::BOOLEAN if grape_boolean_type?(type)

data/lib/grape_oas/api_model_builders/request.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "bigdecimal"
-
 module GrapeOAS
   module ApiModelBuilders
     class Request
@@ -202,162 +200,9 @@ module GrapeOAS
 
         # First try direct lookup (for Ruby class values like String, Integer)
         # Then try class-based lookup (for actual runtime values like "hello", 123)
-        Constants::RUBY_TYPE_MAPPING.fetch(value) do
-          Constants::RUBY_TYPE_MAPPING.fetch(value.class, Constants::SchemaTypes::STRING)
-        end
-      end
-
-      def schema_from_types(types_hash, rule_constraints)
-        schema = GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
-        types_hash.each do |name, dry_type|
-          prop_schema = schema_for_type(dry_type)
-          merge_rule_constraints(prop_schema, rule_constraints[name]) if rule_constraints[name]
-          required = true
-          required = false if dry_type.respond_to?(:optional?) && dry_type.optional?
-          required = false if dry_type.respond_to?(:meta) && dry_type.meta[:omittable]
-          schema.add_property(name, prop_schema, required: required)
-        end
-        schema
-      end
-
-      def schema_for_type(dry_type)
-        if dry_type.respond_to?(:primitive) && dry_type.primitive == Array && dry_type.respond_to?(:member)
-          items_schema = schema_for_type(dry_type.member)
-          schema = GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
-          apply_array_meta_constraints(schema, dry_type.respond_to?(:meta) ? dry_type.meta : {})
-          return schema
-        end
-
-        primitive, member = derive_primitive_and_member(dry_type)
-        if dry_type.respond_to?(:primitive) && dry_type.primitive == Array
-          member ||= dry_type.respond_to?(:member) ? dry_type.member : nil
-          primitive = Array
-        end
-        meta = dry_type.respond_to?(:meta) ? dry_type.meta : {}
-        nullable = dry_type.respond_to?(:optional?) && dry_type.optional?
-        enum_vals = dry_type.respond_to?(:values) ? dry_type.values : nil
-
-        schema = if primitive == Array
-                   items_schema = member ? schema_for_type(member) : default_string_schema
-                   s = GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
-                   apply_array_meta_constraints(s, meta)
-                   s
-                 else
-                   build_schema_for_primitive(primitive)
-                 end
-
-        schema.nullable = nullable
-        schema.enum = enum_vals if enum_vals
-        apply_string_meta_constraints(schema, meta) if primitive == String
-        apply_numeric_meta_constraints(schema, meta) if [Integer, Float, BigDecimal].include?(primitive)
-        schema
-      end
-
-      def derive_primitive_and_member(dry_type)
-        if defined?(Dry::Types::Array::Member) && dry_type.respond_to?(:type) && dry_type.type.is_a?(Dry::Types::Array::Member)
-          return [Array, dry_type.type.member]
-        end
-
-        return [Array, dry_type.member] if dry_type.respond_to?(:member)
-
-        primitive = dry_type.respond_to?(:primitive) ? dry_type.primitive : nil
-        [primitive, nil]
-      end
-
-      def apply_string_meta_constraints(schema, meta)
-        min_length = extract_min_constraint(meta)
-        max_length = extract_max_constraint(meta)
-        schema.min_length = min_length if min_length
-        schema.max_length = max_length if max_length
-        schema.pattern = meta[:pattern] if meta[:pattern]
-      end
-
-      def apply_array_meta_constraints(schema, meta)
-        min_items = extract_min_constraint(meta, :min_items)
-        max_items = extract_max_constraint(meta, :max_items)
-        schema.min_items = min_items if min_items
-        schema.max_items = max_items if max_items
-      end
-
-      # Extract minimum constraint, supporting multiple key names
-      def extract_min_constraint(meta, specific_key = :min_length)
-        meta[:min_size] || meta[specific_key]
-      end
-
-      # Extract maximum constraint, supporting multiple key names
-      def extract_max_constraint(meta, specific_key = :max_length)
-        meta[:max_size] || meta[specific_key]
-      end
-
-      def apply_numeric_meta_constraints(schema, meta)
-        if meta[:gt]
-          schema.minimum = meta[:gt]
-          schema.exclusive_minimum = true
-        elsif meta[:gteq]
-          schema.minimum = meta[:gteq]
-        end
-        if meta[:lt]
-          schema.maximum = meta[:lt]
-          schema.exclusive_maximum = true
-        elsif meta[:lteq]
-          schema.maximum = meta[:lteq]
-        end
-      end
-
-      def merge_rule_constraints(schema, rule_constraints)
-        return unless rule_constraints
-
-        schema.enum ||= rule_constraints[:enum]
-        schema.nullable ||= rule_constraints[:nullable]
-        schema.min_length ||= rule_constraints[:min] if rule_constraints[:min]
-        schema.max_length ||= rule_constraints[:max] if rule_constraints[:max]
-        schema.minimum ||= rule_constraints[:minimum] if rule_constraints[:minimum]
-        schema.maximum ||= rule_constraints[:maximum] if rule_constraints[:maximum]
-        schema.exclusive_minimum ||= rule_constraints[:exclusive_minimum]
-        schema.exclusive_maximum ||= rule_constraints[:exclusive_maximum]
-      end
-
-      # Very small parser for FakeType rule_ast used in tests
-      def extract_rule_constraints(schema_obj)
-        return {} unless schema_obj.respond_to?(:rules)
-
-        # Only supports FakeSchema/FakeType used in tests
-        constraints = Hash.new { |h, k| h[k] = {} }
-        if schema_obj.respond_to?(:types)
-          schema_obj.types.each do |name, dry_type|
-            next unless dry_type.respond_to?(:rule_ast)
-
-            rules = dry_type.rule_ast
-            Array(rules).each do |rule|
-              next unless rule.is_a?(Array)
-
-              _, pred = rule
-              next unless pred.is_a?(Array)
-
-              pname, pargs = pred
-              case pname
-              when :size?
-                min, max = Array(pargs).first
-                constraints[name][:min] = min
-                constraints[name][:max] = max
-              when :maybe
-                constraints[name][:nullable] = true
-              end
-            end
-          end
-        end
-        constraints
-      rescue NoMethodError, TypeError
-        {}
-      end
-
-      def extract_enum_from_core_values(core)
-        return unless core.respond_to?(:values)
-
-        vals = core.values
-        vals if vals.is_a?(Array)
-      rescue NoMethodError
-        nil
+        Constants::RUBY_TYPE_MAPPING[value] ||
+          Constants::RUBY_TYPE_MAPPING[value.class] ||
+          Constants::SchemaTypes::STRING
       end
 
       def convert_contract_schema_to_params(schema)

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

@@ -148,6 +148,8 @@ module GrapeOAS
           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]
+          nullable = SchemaEnhancer.extract_nullable(doc)
+          schema.nullable = (schema.nullable || nullable) if schema.respond_to?(:nullable=)
         end
       end
     end

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

@@ -33,13 +33,18 @@ module GrapeOAS
 
           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_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)
           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)
 
+          # Use TypeResolvers registry for arrays, Dry::Types, and primitives
+          # This resolves stringified types back to actual classes and extracts rich metadata
+          resolved_schema = GrapeOAS.type_resolvers.build_schema(raw_type)
+          return resolved_schema if resolved_schema
+
           build_primitive_schema(raw_type, doc)
         end
 
@@ -88,6 +93,15 @@ module GrapeOAS
           ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
         end
 
+        def build_primitive_array_schema(doc_type, raw_type)
+          type_source = doc_type || raw_type
+          item_type = resolve_schema_type(type_source)
+          ApiModel::Schema.new(
+            type: Constants::SchemaTypes::ARRAY,
+            items: ApiModel::Schema.new(type: item_type, format: Constants.format_for_type(type_source)),
+          )
+        end
+
         def build_simple_array_schema
           ApiModel::Schema.new(
             type: Constants::SchemaTypes::ARRAY,
@@ -170,29 +184,11 @@ module GrapeOAS
           !!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,
-              format: Constants.format_for_type(member_type),
-            ),
-          )
-        end
-
         def resolve_entity_class(type)
           return nil unless defined?(Grape::Entity)
           return type if type.is_a?(Class) && type <= Grape::Entity
@@ -205,7 +201,7 @@ module GrapeOAS
           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}"
+          GrapeOAS.logger.warn("Could not resolve entity constant '#{const_name}': #{e.message}")
           nil
         end
       end

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

@@ -11,7 +11,7 @@ module GrapeOAS
         # @param spec [Hash] the parameter specification
         # @param doc [Hash] the documentation hash
         def self.apply(schema, spec, doc)
-          nullable = extract_nullable(spec, doc)
+          nullable = extract_nullable(doc)
 
           schema.description ||= doc[:desc]
           # Preserve existing nullable: true (e.g., from [Type, Nil] optimization)
@@ -19,17 +19,16 @@ module GrapeOAS
 
           apply_additional_properties(schema, doc)
           apply_format_and_example(schema, doc)
-          apply_constraints(schema, doc)
+          SchemaConstraints.apply(schema, doc)
           apply_values(schema, spec)
         end
 
-        # Extracts nullable flag from spec and documentation.
+        # Extracts nullable flag from a documentation hash.
         #
-        # @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
+        def self.extract_nullable(doc)
+          doc[:nullable] || (doc[:x].is_a?(Hash) && doc[:x][:nullable]) || false
         end
 
         class << self
@@ -51,38 +50,24 @@ module GrapeOAS
             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.
-          # For array schemas, applies enum to items (since values constrain array elements).
-          # For oneOf schemas, applies enum to each non-null variant.
           def apply_values(schema, spec)
-            values = spec[:values]
+            values = ValuesNormalizer.normalize(spec[:values], context: "parameter 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?
+              if one_of_schema?(schema)
+                schema.one_of.each do |variant|
+                  next if null_type_schema?(variant)
+                  next unless range_compatible_with_schema?(values, variant)
+
+                  RangeUtils.apply_to_schema(variant, values)
+                end
+              elsif array_schema_with_items?(schema)
+                RangeUtils.apply_to_schema(schema.items, values)
+              else
+                RangeUtils.apply_to_schema(schema, values)
+              end
+            elsif values.is_a?(Array) && !values.empty?
               apply_enum_values(schema, values)
             end
           end
@@ -98,7 +83,7 @@ module GrapeOAS
                 compatible_values = filter_compatible_values(variant, values)
 
                 # Only apply enum if there are compatible values
-                variant.enum = compatible_values if compatible_values.any? && variant.respond_to?(:enum=)
+                variant.enum = compatible_values if !compatible_values.empty? && variant.respond_to?(:enum=)
               end
             elsif array_schema_with_items?(schema)
               # For array schemas, apply enum to items (values constrain array elements)
@@ -110,7 +95,7 @@ module GrapeOAS
           end
 
           def one_of_schema?(schema)
-            schema.respond_to?(:one_of) && schema.one_of.is_a?(Array) && schema.one_of.any?
+            schema.respond_to?(:one_of) && schema.one_of.is_a?(Array) && !schema.one_of.empty?
           end
 
           def null_type_schema?(schema)
@@ -159,26 +144,14 @@ module GrapeOAS
             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
+
+          def range_compatible_with_schema?(range, schema)
+            numeric_type = RangeUtils::NUMERIC_TYPES.include?(schema.type)
+            RangeUtils.numeric_range?(range) ? numeric_type : !numeric_type
+          end
         end
       end
     end

data/lib/grape_oas/constants.rb

@@ -35,6 +35,22 @@ module GrapeOAS
       ALL = [JSON, XML, FORM_URLENCODED, MULTIPART_FORM].freeze
     end
 
+    # Nullable representation strategies for different OpenAPI versions.
+    # Passed via `nullable_strategy:` option to control how nullable fields
+    # are represented in the generated schema.
+    module NullableStrategy
+      # OAS 3.0: emits `"nullable": true` alongside the type
+      KEYWORD = :keyword
+      # OAS 3.1: emits `"type": ["string", "null"]` (JSON Schema style)
+      TYPE_ARRAY = :type_array
+      # OAS 2.0: emits `"x-nullable": true` extension
+      EXTENSION = :extension
+    end
+
+    # Maximum number of elements to expand from a non-numeric Range into an enum array.
+    # Prevents OOM on wide string ranges (e.g. "a".."zzzzzz").
+    MAX_ENUM_RANGE_SIZE = 100
+
     # Default values for OpenAPI spec when not provided by user
     module Defaults
       LICENSE_NAME = "Proprietary"
@@ -49,13 +65,16 @@ module GrapeOAS
     RUBY_TYPE_MAPPING = {
       Integer => SchemaTypes::INTEGER,
       Float => SchemaTypes::NUMBER,
-      BigDecimal => SchemaTypes::NUMBER,
       TrueClass => SchemaTypes::BOOLEAN,
       FalseClass => SchemaTypes::BOOLEAN,
       Array => SchemaTypes::ARRAY,
       Hash => SchemaTypes::OBJECT,
       File => SchemaTypes::FILE
-    }.freeze
+    }.tap do |mapping|
+      mapping.default_proc = lambda do |_hash, key|
+        key.is_a?(Class) && key.to_s == "BigDecimal" ? SchemaTypes::NUMBER : nil
+      end
+    end.freeze
 
     # String type name to schema type and format mapping (lowercase).
     # Supports lookup with any case via primitive_type helper.

data/lib/grape_oas/doc_key_normalizer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  # Normalizes documentation hash keys so callers can use symbol access
+  # uniformly. String keys that look like OpenAPI extensions ("x-*") are
+  # kept as strings; all other keys are converted to symbols.
+  module DocKeyNormalizer
+    def self.normalize(doc)
+      return doc if doc.empty?
+
+      doc.transform_keys { |k| k.to_s.start_with?("x-") ? k.to_s : k.to_sym }
+    end
+  end
+end

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

@@ -10,11 +10,13 @@ module GrapeOAS
 
         # OAS2-specific fields: consumes, produces, parameters (including body)
         def build_version_specific_fields
+          strategy = @options[:nullable_strategy]
+
           {
             "consumes" => consumes,
             "produces" => produces,
-            "parameters" => Parameter.new(@op, @ref_tracker).build,
-            "responses" => Response.new(@op.responses, @ref_tracker).build
+            "parameters" => Parameter.new(@op, @ref_tracker, nullable_strategy: strategy).build,
+            "responses" => Response.new(@op.responses, @ref_tracker, nullable_strategy: strategy).build
           }
         end
 

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

@@ -18,9 +18,10 @@ module GrapeOAS
           "uuid" => { type: Constants::SchemaTypes::STRING, format: "uuid" }
         }.freeze
 
-        def initialize(operation, ref_tracker = nil)
+        def initialize(operation, ref_tracker = nil, nullable_strategy: nil)
           @op = operation
           @ref_tracker = ref_tracker
+          @nullable_strategy = nullable_strategy
         end
 
         def build
@@ -140,7 +141,7 @@ module GrapeOAS
             ref_name = schema.canonical_name.gsub("::", "_")
             { "$ref" => "#/definitions/#{ref_name}" }
           else
-            Schema.new(schema, @ref_tracker).build
+            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
           end
         end
       end

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

@@ -11,6 +11,7 @@ module GrapeOAS
         # Build OAS2-specific operation
         def build_operation(operation)
           Operation.new(operation, @ref_tracker,
+                        nullable_strategy: @options[:nullable_strategy],
                         suppress_default_error_response: @options[:suppress_default_error_response],).build
         end
       end