grape-oas 1.2.0 → 1.4.0

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

@@ -29,13 +29,7 @@ module GrapeOAS
         #
         # @return [Array] list of entity exposures
         def exposures
-          return [] unless @entity_class.respond_to?(:root_exposures)
-
-          root = @entity_class.root_exposures
-          list = root.instance_variable_get(:@exposures) || []
-          Array(list)
-        rescue NoMethodError
-          []
+          EntityIntrospectorSupport.exposures(@entity_class)
         end
 
         # Gets the exposures defined on a parent entity.
@@ -43,38 +37,43 @@ module GrapeOAS
         # @param parent_entity [Class] the parent entity class
         # @return [Array] list of parent exposures
         def parent_exposures(parent_entity)
-          return [] unless parent_entity.respond_to?(:root_exposures)
-
-          root = parent_entity.root_exposures
-          list = root.instance_variable_get(:@exposures) || []
-          Array(list)
-        rescue NoMethodError
-          []
+          EntityIntrospectorSupport.exposures(parent_entity)
         end
 
         # Builds a schema for an exposure.
         #
         # @param exposure the entity exposure
-        # @param doc [Hash] the documentation hash
         # @return [ApiModel::Schema] the built schema
         def schema_for_exposure(exposure, doc)
-          opts = exposure.instance_variable_get(:@options) || {}
-          type = opts[:using] || doc[:type] || doc["type"]
+          opts = exposure_options(exposure)
+          type = opts[:using] || doc[:type]
 
-          schema = build_exposure_base_schema(type)
-          apply_exposure_properties(schema, doc)
-          apply_exposure_constraints(schema, doc)
+          schema = type_resolver.build_exposure_base_schema(type)
+          schema = apply_exposure_properties(schema, doc)
+          SchemaConstraints.apply(schema, doc)
           schema
         end
 
+        # Builds the property schema for an exposure, routing nesting exposures
+        # to the inline-object path. Wraps in array if doc[:is_array] is set.
+        #
+        # @param exposure the entity exposure
+        # @param doc [Hash] normalized documentation hash
+        # @return [ApiModel::Schema]
+        def build_property_schema(exposure, doc)
+          prop_schema = if nesting_exposure?(exposure)
+                          build_nesting_exposure_schema(exposure, doc)
+                        else
+                          schema_for_exposure(exposure, doc)
+                        end
+          wrap_in_array_if_needed(prop_schema, doc)
+        end
+
         # Checks if an exposure should be included in the schema.
         #
         # @param exposure the entity exposure
         # @return [Boolean] true if exposed
-        def exposed?(exposure)
-          exposure.instance_variable_get(:@conditions) || []
-          true
-        rescue NoMethodError
+        def exposed?(_exposure)
           true
         end
 
@@ -97,14 +96,40 @@ module GrapeOAS
         # @return [Boolean] true if merge exposure
         def merge_exposure?(exposure, doc, opts)
           merge_flag = PropertyExtractor.extract_merge_flag(exposure, doc, opts)
-          merge_flag && resolve_entity_from_opts(exposure, doc)
+          merge_flag && type_resolver.resolve_entity_from_opts(exposure, doc)
+        end
+
+        # Returns the options hash for an exposure.
+        #
+        # @param exposure the entity exposure
+        # @return [Hash]
+        def exposure_options(exposure)
+          exposure.instance_variable_get(:@options) || {}
+        end
+
+        # Determines whether a property should be marked required.
+        # Explicit doc[:required] takes precedence; conditional exposures
+        # default to false; unconditional exposures default to true.
+        #
+        # @param doc [Hash] normalized documentation hash
+        # @param exposure the entity exposure
+        # @return [Boolean]
+        def determine_required(doc, exposure)
+          return doc[:required] unless doc[:required].nil?
+          return false if conditional?(exposure)
+
+          true
         end
 
         private
 
+        def type_resolver
+          @type_resolver ||= TypeSchemaResolver.new(stack: @stack, registry: @registry)
+        end
+
         def add_exposure_to_schema(schema, exposure)
-          doc = exposure.documentation || {}
-          opts = exposure.instance_variable_get(:@options) || {}
+          doc = normalize_doc_keys(exposure.documentation || {})
+          opts = exposure_options(exposure)
 
           if merge_exposure?(exposure, doc, opts)
             merge_exposure_into_schema(schema, exposure, doc)
@@ -114,149 +139,127 @@ module GrapeOAS
         end
 
         def merge_exposure_into_schema(schema, exposure, doc)
-          merged_schema = schema_for_merge(exposure, doc)
+          merged_schema = type_resolver.schema_for_merge(exposure, doc)
           merged_schema.properties.each do |n, ps|
             schema.add_property(n, ps, required: merged_schema.required.include?(n))
           end
         end
 
         def add_property_from_exposure(schema, exposure, doc)
-          prop_schema = schema_for_exposure(exposure, doc)
+          prop_schema = build_property_schema(exposure, doc)
           required = determine_required(doc, exposure)
-          prop_schema = wrap_in_array_if_needed(prop_schema, doc)
           schema.add_property(exposure.key.to_s, prop_schema, required: required)
         end
 
-        def determine_required(doc, exposure)
-          # If explicitly set in documentation, use that value
-          return doc[:required] unless doc[:required].nil?
-
-          # Conditional exposures are not required (may be absent from output)
-          return false if conditional?(exposure)
-
-          # Unconditional exposures are required by default (always present in output)
-          true
-        end
-
         def wrap_in_array_if_needed(prop_schema, doc)
-          is_array = doc[:is_array] || doc["is_array"]
+          is_array = doc[:is_array]
           return prop_schema unless is_array
 
           ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: prop_schema)
         end
 
-        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
-            # Array class itself - create array with string items
-            ApiModel::Schema.new(
-              type: Constants::SchemaTypes::ARRAY,
-              items: ApiModel::Schema.new(type: Constants::SchemaTypes::STRING),
-            )
-          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)
+        # Detects block-based nesting exposures (NestingExposure) that should become
+        # inline object schemas. Only triggers when no entity class is via `using:`.
+        def nesting_exposure?(exposure)
+          return false unless exposure.respond_to?(:nesting?) && exposure.nesting?
+
+          doc = normalize_doc_keys(exposure.documentation || {})
+          opts = exposure_options(exposure)
+          # Extra !opts[:using] catches using: set to a non-entity class (e.g. String)
+          !type_resolver.resolve_grape_entity_class(opts, doc) && !opts[:using]
+        end
+
+        # Builds an inline object schema from a NestingExposure's child exposures.
+        # Duplicate-key children (conditional branches) are merged via NestingMerger.
+        def build_nesting_exposure_schema(exposure, doc)
+          schema = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+          return schema unless exposure.respond_to?(:nested_exposures)
+
+          nesting_accum = {}
+          nesting_required = Hash.new { |h, k| h[k] = [] }
+          Array(exposure.nested_exposures).each do |child_exposure|
+            if nesting_exposure?(child_exposure)
+              key = child_exposure.key.to_s
+              child_doc = normalize_doc_keys(child_exposure.documentation || {})
+              child_schema = build_property_schema(child_exposure, child_doc)
+              nesting_required[key] << determine_required(child_doc, child_exposure)
+              nesting_accum[key] = NestingMerger.merge(nesting_accum[key], child_schema)
+            else
+              add_exposure_to_schema(schema, child_exposure)
+            end
           end
+
+          # ALL branches must agree for the property to be required.
+          nesting_accum.each do |key, merged_schema|
+            schema.add_property(key, merged_schema, required: nesting_required[key].all?)
+          end
+
+          schema = apply_exposure_properties(schema, doc)
+          SchemaConstraints.apply(schema, doc)
+          schema
         end
 
         def apply_exposure_properties(schema, doc)
-          schema.nullable = doc[:nullable] || doc["nullable"] || false
-          schema.enum = doc[:values] || doc["values"] if doc[:values] || doc["values"]
-          schema.description = doc[:desc] || doc["desc"] if doc[:desc] || doc["desc"]
-          schema.format = doc[:format] || doc["format"] if doc[:format] || doc["format"]
-          schema.examples = doc[:example] || doc["example"] if schema.respond_to?(:examples=) && (doc[:example] || doc["example"])
+          schema.nullable = doc[:nullable] || false
+          raw_values = doc[:values]
+          if raw_values
+            normalized = ValuesNormalizer.normalize(raw_values, context: "entity exposure values")
+            if normalized.is_a?(Array) && !normalized.empty?
+              schema = apply_enum_to_schema(schema, normalized)
+            elsif normalized.is_a?(Range)
+              RangeUtils.apply_to_schema(schema, normalized)
+            end
+          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.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]
           schema.defs = defs if defs.is_a?(Hash)
           x_ext = extract_extensions(doc)
           schema.extensions = x_ext if x_ext && schema.respond_to?(:extensions=)
+          schema
         end
 
-        def apply_exposure_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
-
-        def schema_for_type(type)
-          case type
-          when Class
-            schema_for_class_type(type)
-          when String, Symbol
-            schema_for_string_type(type.to_s)
-          else
-            default_string_schema
-          end
-        end
-
-        def schema_for_class_type(type)
-          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
+        # 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.
+        #
+        # @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.enum = values
+            return schema
           end
-        end
 
-        def schema_for_string_type(type_name)
-          entity_class = resolve_entity_from_string(type_name)
-          if entity_class
-            GrapeOAS.introspectors.build_schema(entity_class, stack: @stack, registry: @registry)
+          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.enum = values
+              schema.items = items_dup
+            else
+              schema.items.enum = values
+            end
           else
-            schema_type = Constants.primitive_type(type_name) || Constants::SchemaTypes::STRING
-            ApiModel::Schema.new(type: schema_type)
+            schema.enum = values
           end
+          schema
         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)
-          return nil unless Object.const_defined?(type_name, false)
-
-          klass = Object.const_get(type_name, false)
-          klass if klass.is_a?(Class) && klass <= Grape::Entity
-        rescue NameError
-          nil
-        end
-
-        def schema_for_merge(exposure, doc)
-          using_class = resolve_entity_from_opts(exposure, doc)
-          return ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT) unless using_class
-
-          child = GrapeOAS.introspectors.build_schema(using_class, stack: @stack, registry: @registry)
-          merged = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
-          child.properties.each do |n, ps|
-            merged.add_property(n, ps, required: child.required.include?(n))
-          end
-          merged
-        end
-
-        def resolve_entity_from_opts(exposure, doc)
-          opts = exposure.instance_variable_get(:@options) || {}
-          type = opts[:using] || doc[:type] || doc["type"]
-          return type if defined?(Grape::Entity) && type.is_a?(Class) && type <= Grape::Entity
-
-          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),
-          )
+        def normalize_doc_keys(doc)
+          DocKeyNormalizer.normalize(doc)
         end
       end
     end

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

@@ -16,12 +16,7 @@ module GrapeOAS
         # @param entity_class [Class] the entity class to check
         # @return [Class, nil] the parent entity class or nil
         def self.find_parent_entity(entity_class)
-          return nil unless defined?(Grape::Entity)
-
-          parent = entity_class.superclass
-          return nil unless parent && parent < Grape::Entity && parent != Grape::Entity
-
-          parent
+          EntityIntrospectorSupport.find_parent_entity(entity_class)
         end
 
         # Checks if an entity inherits from a parent that uses discriminator.
@@ -46,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],
           )
 
@@ -77,35 +72,16 @@ module GrapeOAS
         end
 
         def add_child_property(child_schema, exposure, processor)
-          doc = exposure.documentation || {}
-          opts = exposure.instance_variable_get(:@options) || {}
+          doc = DocKeyNormalizer.normalize(exposure.documentation || {})
+          opts = processor.exposure_options(exposure)
 
           return if processor.merge_exposure?(exposure, doc, opts)
 
-          prop_schema = processor.schema_for_exposure(exposure, doc)
-          required = determine_required(doc, exposure, processor)
-          prop_schema = wrap_in_array_if_needed(prop_schema, doc)
+          prop_schema = processor.build_property_schema(exposure, doc)
+          required = processor.determine_required(doc, exposure)
 
           child_schema.add_property(exposure.key.to_s, prop_schema, required: required)
         end
-
-        def determine_required(doc, exposure, processor)
-          # If explicitly set in documentation, use that value
-          return doc[:required] unless doc[:required].nil?
-
-          # Conditional exposures are not required (may be absent from output)
-          return false if processor.conditional?(exposure)
-
-          # Unconditional exposures are required by default (always present in output)
-          true
-        end
-
-        def wrap_in_array_if_needed(prop_schema, doc)
-          is_array = doc[:is_array] || doc["is_array"]
-          return prop_schema unless is_array
-
-          ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: prop_schema)
-        end
       end
     end
   end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module EntityIntrospectorSupport
+      # Merges duplicate-key nesting exposure branches into a single schema,
+      # preserving properties from all branches.
+      module NestingMerger
+        MAX_MERGE_DEPTH = 10 # Grape nesting rarely exceeds 3-4 levels
+
+        class << self
+          # @param accum [ApiModel::Schema, nil] accumulated schema from previous branches
+          # @param current [ApiModel::Schema] schema from the current branch
+          # @param depth [Integer] current recursion depth (guarded by MAX_MERGE_DEPTH)
+          # @return [ApiModel::Schema] merged schema
+          def merge(accum, current, depth = 0)
+            return current unless accum
+            return accum if current.equal?(accum)
+
+            # Unwrap array schemas to merge their items, then re-wrap
+            if array_of_objects?(accum) && array_of_objects?(current)
+              merged_items = merge(accum.items, current.items, depth + 1)
+              merged_array = ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: merged_items)
+              copy_branch_metadata(merged_array, accum)
+              copy_branch_metadata(merged_array, current)
+              return merged_array
+            end
+
+            return accum unless current&.type == Constants::SchemaTypes::OBJECT
+            return current unless accum.type == Constants::SchemaTypes::OBJECT
+
+            merge_object_schemas(accum, current, depth)
+          end
+
+          private
+
+          def merge_object_schemas(accum, current, depth)
+            shared_required = accum.required & current.required
+            merged = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+            copy_branch_metadata(merged, accum)
+            copy_branch_metadata(merged, current)
+
+            accum.properties.each do |n, s|
+              merged.add_property(n, s, required: shared_required.include?(n))
+            end
+
+            current.properties.each do |n, s|
+              existing = merged.properties[n]
+              if existing && mergeable_schemas?(existing, s)
+                if depth < MAX_MERGE_DEPTH
+                  merged.properties[n] = merge(existing, s, depth + 1)
+                else
+                  GrapeOAS.logger.warn(
+                    "NestingMerger: property '#{n}' exceeds maximum merge depth " \
+                    "(#{MAX_MERGE_DEPTH}); using current branch value instead of merging",
+                  )
+                  merged.add_property(n, s, required: shared_required.include?(n))
+                end
+              else
+                merged.add_property(n, s, required: shared_required.include?(n))
+              end
+            end
+            merged
+          end
+
+          # Copies scalar metadata. First non-nil wins for description/format/examples;
+          # nullable uses OR; extensions are merged (last branch wins for overlapping keys).
+          def copy_branch_metadata(merged, source)
+            merged.description ||= source.description
+            merged.nullable = true if source.nullable
+            merged.format ||= source.format
+            merged.examples ||= source.examples if source.respond_to?(:examples)
+            return unless source.respond_to?(:extensions) && source.extensions
+
+            existing = merged.extensions || {}
+            merged.extensions = existing.merge(dup_hash_recursive(source.extensions))
+          end
+
+          def mergeable_schemas?(left, right)
+            return true if left.type == Constants::SchemaTypes::OBJECT && right.type == Constants::SchemaTypes::OBJECT
+
+            array_of_objects?(left) && array_of_objects?(right)
+          end
+
+          def array_of_objects?(schema)
+            schema&.type == Constants::SchemaTypes::ARRAY &&
+              schema.items&.type == Constants::SchemaTypes::OBJECT
+          end
+
+          # Recursive dup for extension hashes. Non-collection values are shared (safe for frozen literals).
+          def dup_hash_recursive(hash)
+            hash.each_with_object({}) do |(k, v), result|
+              result[k] = case v
+                          when Hash then dup_hash_recursive(v)
+                          when Array then v.map { |e| e.is_a?(Hash) ? dup_hash_recursive(e) : e }
+                          else v
+                          end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -12,7 +12,8 @@ module GrapeOAS
           # @param hash [Hash] the documentation hash
           # @return [String, nil] the description value
           def extract_description(hash)
-            hash[:description] || hash[:desc]
+            desc = hash[:description] || hash[:desc]
+            desc.is_a?(String) ? desc : nil
           end
 
           # Extracts nullable flag from a documentation hash.

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module EntityIntrospectorSupport
+      # Resolves OpenAPI schemas from Grape Entity exposure types.
+      # Handles primitives, Grape::Entity subclasses (via recursive introspection),
+      # and merge exposures. Extracted from ExposureProcessor so the type-resolution
+      # concern can be read and tested in isolation.
+      class TypeSchemaResolver
+        include GrapeOAS::ApiModelBuilders::Concerns::OasUtilities
+
+        def initialize(stack:, registry:)
+          @stack = stack
+          @registry = registry
+        end
+
+        # Builds the base schema for an exposure's type annotation.
+        # Handles array literals, the Array class, Hash, and all scalar types.
+        #
+        # @param type [Class, Array, String, Symbol, nil] the type annotation
+        # @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
+            # Array class itself - create array with string items
+            ApiModel::Schema.new(
+              type: Constants::SchemaTypes::ARRAY,
+              items: ApiModel::Schema.new(type: Constants::SchemaTypes::STRING),
+            )
+          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)
+          end
+        end
+
+        # Builds and returns a flattened object schema from the merge-target entity.
+        # Returns an empty object schema when no entity can be resolved.
+        #
+        # @param exposure the entity exposure
+        # @param doc [Hash] normalized documentation hash
+        # @return [ApiModel::Schema]
+        def schema_for_merge(exposure, doc)
+          using_class = resolve_entity_from_opts(exposure, doc)
+          return ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT) unless using_class
+
+          child = GrapeOAS.introspectors.build_schema(using_class, stack: @stack, registry: @registry)
+          merged = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+          child.properties.each do |n, ps|
+            merged.add_property(n, ps, required: child.required.include?(n))
+          end
+          merged
+        end
+
+        # Resolves the Grape::Entity class referenced by an exposure's options or doc.
+        #
+        # @param exposure the entity exposure
+        # @param doc [Hash] normalized documentation hash
+        # @return [Class, nil] the entity class or nil
+        def resolve_entity_from_opts(exposure, doc)
+          opts = exposure.instance_variable_get(:@options) || {}
+          resolve_grape_entity_class(opts, doc)
+        end
+
+        # Checks if opts or doc point to a Grape::Entity subclass.
+        #
+        # @param opts [Hash] exposure options
+        # @param doc [Hash] normalized documentation hash
+        # @return [Class, nil] the entity class or nil
+        def resolve_grape_entity_class(opts, doc)
+          type = opts[:using] || doc[:type]
+          return type if defined?(Grape::Entity) && type.is_a?(Class) && type <= Grape::Entity
+
+          nil
+        end
+
+        private
+
+        def schema_for_type(type)
+          case type
+          when Class
+            schema_for_class_type(type)
+          when String, Symbol
+            schema_for_string_type(type.to_s)
+          else
+            default_string_schema
+          end
+        end
+
+        def schema_for_class_type(type)
+          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
+          end
+        end
+
+        def schema_for_string_type(type_name)
+          entity_class = resolve_entity_from_string(type_name)
+          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)
+          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)
+          return nil unless Object.const_defined?(type_name, false)
+
+          klass = Object.const_get(type_name, false)
+          klass if klass.is_a?(Class) && klass <= Grape::Entity
+        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
+end