grape-oas 1.3.0 → 1.5.0

data/lib/grape_oas/introspectors/entity_introspector_support/exposure_processor.rb

@@ -19,8 +19,6 @@ module GrapeOAS
         # @param schema [ApiModel::Schema] the schema to populate
         def add_exposures_to_schema(schema)
           exposures.each do |exposure|
-            next unless exposed?(exposure)
-
             add_exposure_to_schema(schema, exposure)
           end
         end
@@ -73,8 +71,11 @@ module GrapeOAS
         #
         # @param exposure the entity exposure
         # @return [Boolean] true if exposed
-        def exposed?(_exposure)
-          true
+        def exposed?(exposure)
+          doc = normalize_doc_keys(exposure.documentation || {})
+          hidden = doc[:hidden]
+          hidden = hidden.call if hidden.respond_to?(:call)
+          !hidden
         end
 
         # Checks if an exposure is conditional.
@@ -128,6 +129,8 @@ module GrapeOAS
         end
 
         def add_exposure_to_schema(schema, exposure)
+          return unless exposed?(exposure)
+
           doc = normalize_doc_keys(exposure.documentation || {})
           opts = exposure_options(exposure)
 
@@ -155,7 +158,9 @@ module GrapeOAS
           is_array = doc[:is_array]
           return prop_schema unless is_array
 
-          ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: prop_schema)
+          array_schema = ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: prop_schema)
+          array_schema.examples = doc[:example] if array_valued_example?(doc)
+          array_schema
         end
 
         # Detects block-based nesting exposures (NestingExposure) that should become
@@ -178,6 +183,8 @@ module GrapeOAS
           nesting_accum = {}
           nesting_required = Hash.new { |h, k| h[k] = [] }
           Array(exposure.nested_exposures).each do |child_exposure|
+            next unless exposed?(child_exposure)
+
             if nesting_exposure?(child_exposure)
               key = child_exposure.key.to_s
               child_doc = normalize_doc_keys(child_exposure.documentation || {})
@@ -200,7 +207,16 @@ module GrapeOAS
         end
 
         def apply_exposure_properties(schema, doc)
-          schema.nullable = doc[:nullable] || false
+          nullable = PropertyExtractor.extract_nullable(doc)
+          if nullable && schema.canonical_name
+            # Don't mutate the shared cached entity schema. Create a wrapper with
+            # all_of so the exporter emits { nullable: true, allOf: [{ $ref }] }.
+            # collect_refs traverses all_of and registers the original schema as a
+            # component, keeping its definition free of this property's nullable.
+            schema = ApiModel::Schema.new(nullable: true, all_of: [schema])
+          else
+            schema.nullable = nullable
+          end
           raw_values = doc[:values]
           if raw_values
             normalized = ValuesNormalizer.normalize(raw_values, context: "entity exposure values")
@@ -212,7 +228,7 @@ module GrapeOAS
           end
           schema.description = doc[:desc] if doc[:desc]
           schema.format = doc[:format] if doc[:format]
-          schema.examples = doc[:example] if schema.respond_to?(:examples=) && doc[:example]
+          schema = apply_example_to_schema(schema, doc[:example]) if doc.key?(:example) && !array_valued_example?(doc)
           schema.additional_properties = doc[:additional_properties] if doc.key?(:additional_properties)
           schema.unevaluated_properties = doc[:unevaluated_properties] if doc.key?(:unevaluated_properties)
           defs = doc[:defs] || doc[:$defs]
@@ -223,17 +239,24 @@ module GrapeOAS
         end
 
         # Cached entity schemas (via using:) are shared across all exposures that
-        # reference the same entity — dup before setting enum to avoid mutating
-        # the shared schema; emit a warning so users know a dup occurred.
+        # reference the same entity — dup before mutating them (enum, example, ...)
+        # to avoid corrupting the shared schema; emit a warning so users know a
+        # dup occurred.
         #
+        # @return [ApiModel::Schema] a dup of schema with canonical_name cleared
+        def dup_cached_schema(schema, reason:, value:)
+          GrapeOAS.logger.warn(
+            "Duplicating cached schema '#{schema.canonical_name}' to apply #{reason} #{value.inspect}",
+          )
+          dup = schema.dup
+          dup.canonical_name = nil
+          dup
+        end
+
         # @return [ApiModel::Schema] the schema (or a dup) with enum applied
         def apply_enum_to_schema(schema, values)
           if schema.respond_to?(:canonical_name) && schema.canonical_name
-            GrapeOAS.logger.warn(
-              "Duplicating cached schema '#{schema.canonical_name}' to apply enum #{values.inspect}",
-            )
-            schema = schema.dup
-            schema.canonical_name = nil
+            schema = dup_cached_schema(schema, reason: "enum", value: values)
             schema.enum = values
             return schema
           end
@@ -241,13 +264,9 @@ module GrapeOAS
           if schema.type == Constants::SchemaTypes::ARRAY &&
              schema.respond_to?(:items) && schema.items
             if schema.items.respond_to?(:canonical_name) && schema.items.canonical_name
-              GrapeOAS.logger.warn(
-                "Duplicating cached schema '#{schema.items.canonical_name}' to apply enum #{values.inspect}",
-              )
-              schema = schema.dup
-              items_dup = schema.items.dup
-              items_dup.canonical_name = nil
+              items_dup = dup_cached_schema(schema.items, reason: "enum", value: values)
               items_dup.enum = values
+              schema = schema.dup
               schema.items = items_dup
             else
               schema.items.enum = values
@@ -258,6 +277,22 @@ module GrapeOAS
           schema
         end
 
+        def apply_example_to_schema(schema, example)
+          return schema unless schema.respond_to?(:examples=)
+
+          if schema.respond_to?(:canonical_name) && schema.canonical_name
+            schema = dup_cached_schema(schema, reason: "example", value: example)
+          end
+          schema.examples = example
+          schema
+        end
+
+        # True when doc[:example] describes the whole array (not a single item),
+        # i.e. is_array: true and the example is itself an Array.
+        def array_valued_example?(doc)
+          doc[:is_array] && doc[:example].is_a?(Array)
+        end
+
         def normalize_doc_keys(doc)
           DocKeyNormalizer.normalize(doc)
         end

data/lib/grape_oas/introspectors/entity_introspector_support/inheritance_builder.rb

@@ -41,7 +41,7 @@ module GrapeOAS
 
           # Create allOf schema with ref to parent + child properties
           schema = ApiModel::Schema.new(
-            canonical_name: @entity_class.name,
+            canonical_name: EntityIntrospectorSupport.resolve_canonical_name(@entity_class),
             all_of: [parent_schema, child_schema],
           )
 

data/lib/grape_oas/introspectors/entity_introspector_support/property_extractor.rb

@@ -7,6 +7,8 @@ module GrapeOAS
       # All methods are stateless and can be called directly on the class.
       class PropertyExtractor
         class << self
+          include GrapeOAS::ApiModelBuilders::Concerns::OasUtilities
+
           # Extracts description from a documentation hash.
           #
           # @param hash [Hash] the documentation hash
@@ -16,14 +18,6 @@ module GrapeOAS
             desc.is_a?(String) ? desc : nil
           end
 
-          # Extracts nullable flag from a documentation hash.
-          #
-          # @param doc [Hash] the documentation hash
-          # @return [Boolean] true if nullable
-          def extract_nullable(doc)
-            doc[:nullable] || doc["nullable"] || false
-          end
-
           # Extracts merge flag from exposure options and documentation.
           #
           # @param exposure the entity exposure

data/lib/grape_oas/introspectors/entity_introspector_support/type_schema_resolver.rb

@@ -22,7 +22,6 @@ module GrapeOAS
         # @return [ApiModel::Schema]
         def build_exposure_base_schema(type)
           if type.is_a?(Array)
-            # Array instance like [String] - extract inner type
             inner = schema_for_type(type.first)
             ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: inner)
           elsif type == Array
@@ -34,7 +33,7 @@ module GrapeOAS
           elsif type.is_a?(Hash) || type == Hash
             ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
           else
-            schema_for_type(type) || ApiModel::Schema.new(type: Constants::SchemaTypes::STRING)
+            schema_for_type(type)
           end
         end
 
@@ -87,7 +86,7 @@ module GrapeOAS
           when String, Symbol
             schema_for_string_type(type.to_s)
           else
-            default_string_schema
+            GrapeOAS.type_resolvers.build_schema(type)
           end
         end
 
@@ -95,7 +94,7 @@ module GrapeOAS
           if defined?(Grape::Entity) && type <= Grape::Entity
             GrapeOAS.introspectors.build_schema(type, stack: @stack, registry: @registry)
           else
-            build_schema_for_primitive(type) || default_string_schema
+            GrapeOAS.type_resolvers.build_schema(type)
           end
         end
 
@@ -104,15 +103,10 @@ module GrapeOAS
           if entity_class
             GrapeOAS.introspectors.build_schema(entity_class, stack: @stack, registry: @registry)
           else
-            schema_type = Constants.primitive_type(type_name) || Constants::SchemaTypes::STRING
-            ApiModel::Schema.new(type: schema_type)
+            GrapeOAS.type_resolvers.build_schema(type_name)
           end
         end
 
-        def default_string_schema
-          ApiModel::Schema.new(type: Constants::SchemaTypes::STRING)
-        end
-
         def resolve_entity_from_string(type_name)
           return nil unless defined?(Grape::Entity)
           return nil unless valid_constant_name?(type_name)
@@ -123,16 +117,6 @@ module GrapeOAS
         rescue NameError
           nil
         end
-
-        def build_schema_for_primitive(type)
-          schema_type = Constants.primitive_type(type)
-          return nil unless schema_type
-
-          ApiModel::Schema.new(
-            type: schema_type,
-            format: Constants.format_for_type(type),
-          )
-        end
       end
     end
   end

data/lib/grape_oas/introspectors/entity_introspector_support.rb

@@ -19,6 +19,30 @@ module GrapeOAS
         []
       end
 
+      # Resolves the canonical name for an entity class, preferring entity_name
+      # when defined on the class itself (via def self. or extend) and non-blank,
+      # falling back to the Ruby class name. Inherited entity_name is ignored to
+      # avoid collisions between parent and child schemas.
+      def self.resolve_canonical_name(entity_class)
+        if defines_own_entity_name?(entity_class)
+          name = entity_class.entity_name
+          name.is_a?(String) && !name.strip.empty? ? name : entity_class.name
+        else
+          entity_class.name
+        end
+      end
+
+      def self.defines_own_entity_name?(entity_class)
+        return false unless entity_class.respond_to?(:entity_name)
+
+        parent = find_parent_entity(entity_class)
+        return true if parent.nil? || !parent.respond_to?(:entity_name)
+
+        entity_class.method(:entity_name).owner !=
+          parent.method(:entity_name).owner
+      end
+      private_class_method :defines_own_entity_name?
+
       # Finds the parent entity class if one exists in the Grape::Entity hierarchy.
       def self.find_parent_entity(entity_class)
         return nil unless defined?(Grape::Entity)

data/lib/grape_oas/range_utils.rb

@@ -34,10 +34,17 @@ module GrapeOAS
 
         return if descending?(first_val, last_val)
 
-        target.minimum = first_val if finite_numeric?(first_val) && target.respond_to?(:minimum=)
+        if finite_numeric?(first_val) && target.respond_to?(:minimum=)
+          coerced_min = coerce_for_json(first_val)
+          target.minimum = coerced_min unless coerced_min.nil?
+        end
+
         return unless finite_numeric?(last_val)
 
-        target.maximum = last_val if target.respond_to?(:maximum=)
+        coerced_max = coerce_for_json(last_val)
+        return if coerced_max.nil?
+
+        target.maximum = coerced_max if target.respond_to?(:maximum=)
         target.exclusive_maximum = range.exclude_end? if target.respond_to?(:exclusive_maximum=)
       end
 
@@ -79,6 +86,22 @@ module GrapeOAS
         val.is_a?(Numeric) && val.finite?
       end
 
+      # Coerce BigDecimal to Float so min/max render as JSON numbers, not strings.
+      # Returns nil when the result overflows to Infinity.
+      def coerce_for_json(val)
+        return val unless defined?(BigDecimal) && val.is_a?(BigDecimal)
+
+        coerced = val.to_f
+        unless coerced.finite?
+          GrapeOAS.logger.warn("BigDecimal value #{val} overflows to Float::INFINITY and cannot be represented in JSON; skipping bound")
+          return nil
+        end
+        if val != BigDecimal(coerced, Float::DIG + 1)
+          GrapeOAS.logger.debug("BigDecimal value #{val} lost precision when coerced to Float #{coerced}")
+        end
+        coerced
+      end
+
       def descending?(first_val, last_val)
         first_val.is_a?(Numeric) && last_val.is_a?(Numeric) && first_val > last_val
       end

data/lib/grape_oas/type_resolvers/array_resolver.rb

@@ -2,13 +2,17 @@
 
 module GrapeOAS
   module TypeResolvers
-    # Resolves array types like "[String]", "[Integer]", "[MyApp::Types::UUID]".
+    # Resolves array types like "[String]", "Array[Integer]", "Set[String, Integer]".
     #
     # Grape converts `type: [SomeClass]` to the string "[SomeClass]" for documentation.
+    # Grape 3.3+ VariantCollectionCoercer#to_s emits "Array[Type, ...]" / "Set[Type, ...]"
+    # for `type: Array[Integer, String]` so documentation tools can tell a collection
+    # of variant members from `types: [Integer, String]` (a scalar oneOf, grape#2758).
+    #
     # This resolver:
     # 1. Detects the array pattern via regex
-    # 2. Extracts the inner type name
-    # 3. Attempts to resolve it back to the actual class via Object.const_get
+    # 2. Extracts the inner type name(s)
+    # 3. Attempts to resolve each name back to the actual class via Object.const_get
     # 4. If resolved, extracts rich metadata (Dry::Types format, primitive, etc.)
     # 5. Falls back to string-based inference if class not available
     #
@@ -20,41 +24,69 @@ module GrapeOAS
     class ArrayResolver
       extend Base
 
-      # Pattern to match Grape's array notation: "[Type]" or "[Module::Type]"
-      # Intentionally narrow: avoid treating multi-type strings like "[String, Integer]" as arrays.
-      ARRAY_PATTERN = /\A\[(?<inner>(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*)\]\z/
+      TYPED_ARRAY_PATTERN = Constants::TypePatterns::TYPED_ARRAY
+      VARIANT_COLLECTION_PATTERN = Constants::TypePatterns::VARIANT_COLLECTION
 
       class << self
         def handles?(type)
           return false unless type.is_a?(String)
 
-          type.match?(ARRAY_PATTERN)
+          type.match?(TYPED_ARRAY_PATTERN) || type.match?(VARIANT_COLLECTION_PATTERN)
         end
 
         def build_schema(type)
-          inner_type_name = extract_inner_type(type)
-          return nil unless inner_type_name
-
-          # Try to resolve the string to an actual class
-          resolved_class = resolve_class(inner_type_name)
-
-          items_schema = if resolved_class
-                           build_schema_from_class(resolved_class)
-                         else
-                           build_schema_from_string(inner_type_name)
-                         end
+          container, type_names = extract_collection(type)
+          return nil unless type_names
 
-          ApiModel::Schema.new(
+          items_schema = build_items_schema(type_names)
+          schema = ApiModel::Schema.new(
             type: Constants::SchemaTypes::ARRAY,
             items: items_schema,
           )
+          schema.unique_items = true if container == "Set"
+          schema
         end
 
         private
 
-        def extract_inner_type(type)
-          match = type.match(ARRAY_PATTERN)
-          match[:inner] if match
+        def extract_collection(type)
+          if (match = type.match(VARIANT_COLLECTION_PATTERN))
+            [match[:container], match[:inner].split(/,\s*/)]
+          elsif (match = type.match(TYPED_ARRAY_PATTERN))
+            [match[:container], [match[:inner]]]
+          end
+        end
+
+        def build_items_schema(type_names)
+          if nullable_type_pair?(type_names)
+            schema = build_items_for_name(type_names.find { |name| !nil_type_name?(name) })
+            schema.nullable = true
+            return schema
+          end
+
+          return build_items_for_name(type_names.first) if type_names.size == 1
+
+          has_nil_type = type_names.any? { |name| nil_type_name?(name) }
+          variants = type_names.reject { |name| nil_type_name?(name) }.map { |name| build_items_for_name(name) }
+          ApiModel::Schema.new(one_of: variants, nullable: has_nil_type ? true : nil)
+        end
+
+        def build_items_for_name(type_name)
+          resolved_class = resolve_class(type_name)
+          if resolved_class
+            build_schema_from_class(resolved_class)
+          else
+            build_schema_from_string(type_name)
+          end
+        end
+
+        def nullable_type_pair?(type_names)
+          type_names.size == 2 && type_names.one? { |name| nil_type_name?(name) }
+        end
+
+        def nil_type_name?(type_name)
+          normalized = type_name.to_s
+          normalized == "NilClass" || normalized == "Nil" || normalized.end_with?("::Nil")
         end
 
         def build_schema_from_class(klass)

data/lib/grape_oas/type_resolvers/base.rb

@@ -49,7 +49,7 @@ module GrapeOAS
       # Checks if this resolver can handle the given type.
       #
       # @param type [String, Class, Object] The type to check (stringified or actual)
-      # @return [Boolean] true if this resolver can handle the type
+      # @return [Boolean]
       def handles?(type)
         raise NotImplementedError, "#{self} must implement .handles?(type)"
       end
@@ -57,7 +57,7 @@ module GrapeOAS
       # Builds an OpenAPI schema from the given type.
       #
       # @param type [String, Class, Object] The type to build schema for
-      # @return [ApiModel::Schema] The built schema
+      # @return [ApiModel::Schema, nil]
       def build_schema(type)
         raise NotImplementedError, "#{self} must implement .build_schema(type)"
       end

data/lib/grape_oas/type_resolvers/default_resolver.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module TypeResolvers
+    # Catch-all used by Registry#build_schema when no registered resolver
+    # matches. Returns a plain string schema for any type. Not registered
+    # in the chain — called automatically by the registry as a built-in
+    # fallback.
+    class DefaultResolver
+      class << self
+        def handles?(_type)
+          true
+        end
+
+        def build_schema(type)
+          logger = GrapeOAS.logger
+          logger.debug { "No type resolver matched #{type.inspect}, falling back to string schema" } if logger.respond_to?(:debug)
+          ApiModel::Schema.new(type: Constants::SchemaTypes::STRING)
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/type_resolvers/dry_type_resolver.rb

@@ -26,7 +26,7 @@ module GrapeOAS
 
           # Handle strings that resolve to Dry::Types
           return false unless type.is_a?(String)
-          return false if type.match?(/\A\[.+\]\z/) # Skip arrays, handled by ArrayResolver
+          return false if type.match?(/\A(?:Array|Set)?\[.+\]\z/) # Skip arrays, handled by ArrayResolver
 
           resolved = resolve_class(type)
           dry_type?(resolved)

data/lib/grape_oas/type_resolvers/primitive_resolver.rb

@@ -4,8 +4,9 @@ module GrapeOAS
   module TypeResolvers
     # Resolves primitive types like "Integer", "String", "Boolean", "Float".
     #
-    # This is the fallback resolver that handles basic Ruby types and their
-    # string representations. It's registered last in the resolver chain.
+    # Handles basic Ruby types and their string representations, including
+    # OpenAPI type name aliases via Constants. Registered before the
+    # catch-all DefaultResolver in the resolver chain.
     #
     class PrimitiveResolver
       extend Base
@@ -13,7 +14,7 @@ module GrapeOAS
       # Known primitive type mappings
       PRIMITIVES = {
         "String" => { type: Constants::SchemaTypes::STRING },
-        "Integer" => { type: Constants::SchemaTypes::INTEGER, format: "int32" },
+        "Integer" => { type: Constants::SchemaTypes::INTEGER },
         "Float" => { type: Constants::SchemaTypes::NUMBER, format: "float" },
         "BigDecimal" => { type: Constants::SchemaTypes::NUMBER, format: "double" },
         "Numeric" => { type: Constants::SchemaTypes::NUMBER },
@@ -33,33 +34,33 @@ module GrapeOAS
 
       class << self
         def handles?(type)
-          type_str = normalize_type(type)
-          PRIMITIVES.key?(type_str) || resolvable_to_primitive?(type)
+          !find_mapping(type).nil?
         end
 
         def build_schema(type)
+          schema_type, format = find_mapping(type)
+          return nil unless schema_type
+
+          ApiModel::Schema.new(type: schema_type, format: format)
+        end
+
+        private
+
+        # Returns [type, format] or nil.
+        def find_mapping(type)
           type_str = normalize_type(type)
 
-          # Check direct mapping first
-          if PRIMITIVES.key?(type_str)
-            mapping = PRIMITIVES[type_str]
-            return ApiModel::Schema.new(
-              type: mapping[:type],
-              format: mapping[:format],
-            )
+          if (mapping = PRIMITIVES[type_str])
+            return [mapping[:type], mapping[:format]]
           end
 
-          # Try to resolve and build schema
-          resolved = resolve_class(type_str)
-          if resolved
-            build_from_resolved(resolved)
-          else
-            # Default fallback
-            ApiModel::Schema.new(type: Constants::SchemaTypes::STRING)
-          end
-        end
+          # OpenAPI type name aliases ("object", "number", "boolean")
+          schema_type = Constants.primitive_type(type_str)
+          return [schema_type, Constants.format_for_type(type_str)] if schema_type
 
-        private
+          mapping = resolved_primitive_mapping(resolve_class(type_str))
+          [mapping[:type], mapping[:format]] if mapping
+        end
 
         def normalize_type(type)
           case type
@@ -72,32 +73,14 @@ module GrapeOAS
           end
         end
 
-        def resolvable_to_primitive?(type)
-          resolved = resolve_class(normalize_type(type))
-          return false unless resolved
-
-          # Dry::Types should be handled by DryTypeResolver.
-          return false if resolved.respond_to?(:primitive)
-
-          resolved_name = resolved.respond_to?(:name) ? resolved.name : resolved.to_s
-          return false if resolved_name.nil? || resolved_name.empty?
+        def resolved_primitive_mapping(resolved)
+          return nil unless resolved
+          return nil if resolved.respond_to?(:primitive) # Dry::Types handled by DryTypeResolver
 
-          PRIMITIVES.key?(resolved_name)
-        end
-
-        def build_from_resolved(klass)
-          # Find mapping by class name
-          type_str = klass.name
-          mapping = PRIMITIVES[type_str]
+          resolved_name = resolved.respond_to?(:name) ? resolved.name : nil
+          return nil if resolved_name.nil? || resolved_name.empty?
 
-          if mapping
-            ApiModel::Schema.new(
-              type: mapping[:type],
-              format: mapping[:format],
-            )
-          else
-            ApiModel::Schema.new(type: Constants::SchemaTypes::STRING)
-          end
+          PRIMITIVES[resolved_name]
         end
       end
     end

data/lib/grape_oas/type_resolvers/registry.rb

@@ -50,31 +50,38 @@ module GrapeOAS
         self
       end
 
-      # Finds the first resolver that can handle the given type.
-      #
-      # @param type [String, Class, Object] The type to resolve
-      # @return [Class, nil] The resolver class, or nil if none found
-      def find(type)
-        @resolvers.find { |resolver| resolver.handles?(type) }
-      end
-
-      # Builds a schema using the appropriate resolver.
+      # Builds a schema using the first resolver that returns non-nil.
+      # Falls back to DefaultResolver when no registered resolver produces
+      # a schema, guaranteeing a non-nil return.
       #
       # @param type [String, Class, Object] The type to build schema for
-      # @return [ApiModel::Schema, nil] The built schema, or nil if no handler found
+      # @return [ApiModel::Schema] The built schema
       def build_schema(type)
-        resolver = find(type)
-        return nil unless resolver
+        @resolvers.each do |resolver|
+          next unless resolver.handles?(type)
+
+          schema = resolver.build_schema(type)
+          return schema if schema
+        end
 
-        resolver.build_schema(type)
+        DefaultResolver.build_schema(type)
       end
 
-      # Checks if any resolver can handle the given type.
+      # Checks if any registered resolver produces a schema for this type.
+      # Does not account for the built-in DefaultResolver fallback, so
+      # returning false does not mean build_schema will return nil — it
+      # will still produce a string schema via DefaultResolver.
       #
       # @param type [String, Class, Object] The type to check
       # @return [Boolean]
+      def registered_resolver_for?(type)
+        !find(type).nil?
+      end
+
+      # @deprecated Use {#registered_resolver_for?} instead.
       def handles?(type)
-        @resolvers.any? { |resolver| resolver.handles?(type) }
+        warn "GrapeOAS::TypeResolvers::Registry#handles? is deprecated, use #registered_resolver_for? instead", uplevel: 1
+        registered_resolver_for?(type)
       end
 
       # Iterates over all registered resolvers.
@@ -108,7 +115,16 @@ module GrapeOAS
 
       private
 
+      def find(type)
+        @resolvers.find { |resolver| resolver.handles?(type) }
+      end
+
       def validate_resolver!(resolver)
+        if resolver == DefaultResolver
+          raise ArgumentError,
+                "DefaultResolver is the built-in fallback and must not be registered in the chain"
+        end
+
         return if resolver.respond_to?(:handles?) && resolver.respond_to?(:build_schema)
 
         raise ArgumentError,