grape-oas 1.0.0

data/lib/grape_oas/introspectors/dry_introspector_support/type_unwrapper.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module DryIntrospectorSupport
+      # Unwraps Dry::Types to extract primitives and member types.
+      #
+      # Dry::Types can be deeply nested with wrappers (Constrained, Sum, etc.).
+      # This module provides utilities to unwrap these types and extract the
+      # underlying primitive type and any array member types.
+      #
+      # @example Unwrapping a constrained type
+      #   core = TypeUnwrapper.unwrap(Dry::Types["strict.string"].constrained(max_size: 10))
+      #   # => Returns the base String type
+      #
+      module TypeUnwrapper
+        # Maximum depth for unwrapping nested Dry::Types (prevents infinite loops)
+        MAX_DEPTH = 5
+
+        module_function
+
+        # Derives the primitive type and member type from a Dry::Types type.
+        #
+        # @param dry_type [Dry::Types::Type] the type to analyze
+        # @return [Array(Class, Object)] tuple of [primitive_class, member_type_or_nil]
+        def derive_primitive_and_member(dry_type)
+          core = unwrap(dry_type)
+
+          return [Array, core.type.member] if array_member_type?(core)
+          return [Array, core.member] if array_with_member?(core)
+
+          primitive = core.respond_to?(:primitive) ? core.primitive : nil
+          [primitive, nil]
+        end
+
+        # Unwraps a Dry::Types type to get to the core type.
+        #
+        # @param dry_type [Dry::Types::Type] the type to unwrap
+        # @return [Dry::Types::Type] the unwrapped core type
+        def unwrap(dry_type)
+          current = dry_type
+          depth = 0
+
+          while current.respond_to?(:type) && depth < MAX_DEPTH
+            inner = current.type
+            break if inner.equal?(current)
+
+            current = inner
+            depth += 1
+          end
+
+          current
+        end
+
+        # Detects if type is a meaningful Dry::Types::Sum (union type like TypeA | TypeB).
+        #
+        # Returns false for nullable sums (nil | String) which are created by maybe(),
+        # as those should be treated as nullable types rather than union types.
+        #
+        # @param dry_type [Dry::Types::Type] the type to check
+        # @return [Boolean] true if it's a meaningful sum type
+        def sum_type?(dry_type)
+          return false unless defined?(Dry::Types::Sum)
+          return false unless dry_type.is_a?(Dry::Types::Sum) || dry_type.class.name&.include?("Sum")
+
+          # Check if this is a "schema sum" (both sides are Hash schemas)
+          # vs a "nullable sum" (one side is NilClass from maybe())
+          schema_sum?(dry_type)
+        end
+
+        # Checks if Sum type represents a union of schemas (not just nullable).
+        #
+        # @param sum_type [Dry::Types::Sum] the sum type to check
+        # @return [Boolean] true if it's a union of 2+ non-nil schemas
+        def schema_sum?(sum_type)
+          return false unless sum_type.respond_to?(:left) && sum_type.respond_to?(:right)
+
+          types = extract_sum_types(sum_type)
+
+          # Filter out NilClass types (from maybe())
+          non_nil_types = types.reject { |t| nil_type?(t) }
+
+          # It's a schema sum if we have 2+ non-nil types and at least one is a Hash schema
+          non_nil_types.length >= 2 && non_nil_types.any? { |t| hash_schema?(t) }
+        end
+
+        # Checks if type is a nil type (from maybe()).
+        #
+        # @param dry_type [Dry::Types::Type] the type to check
+        # @return [Boolean] true if it's a NilClass type
+        def nil_type?(dry_type)
+          return true if dry_type.respond_to?(:primitive) && dry_type.primitive == NilClass
+
+          # Check wrapped type
+          unwrapped = unwrap(dry_type)
+          unwrapped.respond_to?(:primitive) && unwrapped.primitive == NilClass
+        end
+
+        # Checks if type is a Hash schema (has keys defined).
+        #
+        # @param dry_type [Dry::Types::Type] the type to check
+        # @return [Boolean] true if it's a Hash schema with keys
+        def hash_schema?(dry_type)
+          return true if dry_type.respond_to?(:keys) && dry_type.keys.any?
+
+          unwrapped = unwrap(dry_type)
+          unwrapped.respond_to?(:keys) && unwrapped.keys.any?
+        end
+
+        # Recursively extracts all types from a Sum type tree.
+        #
+        # A | B | C becomes Sum(Sum(A, B), C), so we need to traverse the tree.
+        #
+        # @param dry_type [Dry::Types::Type] the sum type to extract from
+        # @param types [Array] accumulator array for types (internal use)
+        # @return [Array<Dry::Types::Type>] all leaf types in the sum
+        def extract_sum_types(dry_type, types = [])
+          if dry_type.respond_to?(:left) && dry_type.respond_to?(:right)
+            extract_sum_types(dry_type.left, types)
+            extract_sum_types(dry_type.right, types)
+          else
+            types << dry_type
+          end
+          types
+        end
+
+        def array_member_type?(core)
+          defined?(Dry::Types::Array::Member) &&
+            core.respond_to?(:type) &&
+            core.type.is_a?(Dry::Types::Array::Member)
+        end
+        private_class_method :array_member_type?
+
+        def array_with_member?(core)
+          core.respond_to?(:member) &&
+            core.respond_to?(:primitive) &&
+            core.primitive == Array
+        end
+        private_class_method :array_with_member?
+      end
+    end
+  end
+end

data/lib/grape_oas/introspectors/entity_introspector.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../api_model_builders/concerns/type_resolver"
+require_relative "entity_introspector_support/cycle_tracker"
+require_relative "entity_introspector_support/discriminator_handler"
+require_relative "entity_introspector_support/inheritance_builder"
+require_relative "entity_introspector_support/property_extractor"
+require_relative "entity_introspector_support/exposure_processor"
+
+module GrapeOAS
+  module Introspectors
+    # Introspector for Grape::Entity classes.
+    # Extracts schema information from entity exposures and documentation.
+    class EntityIntrospector
+      extend Base
+      include GrapeOAS::ApiModelBuilders::Concerns::TypeResolver
+      include GrapeOAS::ApiModelBuilders::Concerns::OasUtilities
+
+      # Checks if the subject is a Grape::Entity class.
+      #
+      # @param subject [Object] The object to check
+      # @return [Boolean] true if subject is a Grape::Entity class
+      def self.handles?(subject)
+        return false unless defined?(Grape::Entity)
+        return subject <= Grape::Entity if subject.is_a?(Class)
+        return false unless subject.is_a?(String) || subject.is_a?(Symbol)
+
+        const_name = subject.to_s
+        return false unless const_name.match?(/\A[A-Z]/)
+        return false unless Object.const_defined?(const_name, false)
+
+        klass = Object.const_get(const_name, false)
+        klass.is_a?(Class) && klass <= Grape::Entity
+      rescue NameError
+        false
+      end
+
+      # Builds a schema from a Grape::Entity class.
+      #
+      # @param subject [Class, String, Symbol] Entity class or its name
+      # @param stack [Array] Recursion stack for cycle detection
+      # @param registry [Hash] Schema registry for caching
+      # @return [ApiModel::Schema] The built schema
+      def self.build_schema(subject, stack: [], registry: {})
+        entity_class = resolve_entity_class(subject)
+        return nil unless entity_class
+
+        new(entity_class, stack: stack, registry: registry).build_schema
+      end
+
+      # Resolves a subject to an entity class.
+      #
+      # @param subject [Class, String, Symbol] Entity class or its name
+      # @return [Class, nil] The resolved entity class
+      def self.resolve_entity_class(subject)
+        return subject if subject.is_a?(Class) && defined?(Grape::Entity) && subject <= Grape::Entity
+        return nil unless subject.is_a?(String) || subject.is_a?(Symbol)
+
+        const_name = subject.to_s
+        return nil unless Object.const_defined?(const_name, false)
+
+        klass = Object.const_get(const_name, false)
+        klass if klass.is_a?(Class) && defined?(Grape::Entity) && klass <= Grape::Entity
+      rescue NameError
+        nil
+      end
+
+      def initialize(entity_class, stack: [], registry: {})
+        @entity_class = entity_class
+        @stack = stack
+        @registry = registry
+      end
+
+      def build_schema
+        return cached_schema if cached_schema_available?
+        return build_inherited_schema if inherits_with_discriminator?
+
+        schema = initialize_or_reuse_schema
+        return cycle_tracker.handle_cycle(schema) if cycle_tracker.cyclic_reference?
+
+        cycle_tracker.with_tracking { populate_schema(schema) }
+      end
+
+      private
+
+      def cached_schema_available?
+        built = @registry[@entity_class]
+        built && !built.properties.empty?
+      end
+
+      def cached_schema
+        @registry[@entity_class]
+      end
+
+      def initialize_or_reuse_schema
+        @registry[@entity_class] ||= ApiModel::Schema.new(
+          type: Constants::SchemaTypes::OBJECT,
+          canonical_name: @entity_class.name,
+          description: nil,
+          nullable: nil,
+        )
+      end
+
+      def populate_schema(schema)
+        doc = entity_doc
+        apply_schema_metadata(schema, doc)
+        exposure_processor.add_exposures_to_schema(schema)
+        schema
+      end
+
+      def apply_schema_metadata(schema, doc)
+        schema.description ||= EntityIntrospectorSupport::PropertyExtractor.extract_description(doc)
+        schema.nullable = EntityIntrospectorSupport::PropertyExtractor.extract_nullable(doc) if schema.nullable.nil?
+        EntityIntrospectorSupport::PropertyExtractor.apply_entity_level_properties(schema, doc)
+        apply_extensions(schema, doc)
+        discriminator_handler.apply(schema)
+      end
+
+      def apply_extensions(schema, doc)
+        root_ext = extract_extensions(doc)
+        schema.extensions = root_ext if root_ext
+      end
+
+      def entity_doc
+        @entity_class.respond_to?(:documentation) ? (@entity_class.documentation || {}) : {}
+      rescue NoMethodError
+        {}
+      end
+
+      def inherits_with_discriminator?
+        EntityIntrospectorSupport::InheritanceBuilder.inherits_with_discriminator?(@entity_class)
+      end
+
+      def build_inherited_schema
+        parent = EntityIntrospectorSupport::InheritanceBuilder.find_parent_entity(@entity_class)
+        inheritance_builder.build_inherited_schema(parent)
+      end
+
+      def cycle_tracker
+        @cycle_tracker ||= EntityIntrospectorSupport::CycleTracker.new(@entity_class, @stack)
+      end
+
+      def discriminator_handler
+        @discriminator_handler ||= EntityIntrospectorSupport::DiscriminatorHandler.new(@entity_class)
+      end
+
+      def exposure_processor
+        @exposure_processor ||= EntityIntrospectorSupport::ExposureProcessor.new(
+          @entity_class,
+          stack: @stack,
+          registry: @registry,
+        )
+      end
+
+      def inheritance_builder
+        @inheritance_builder ||= EntityIntrospectorSupport::InheritanceBuilder.new(
+          @entity_class,
+          stack: @stack,
+          registry: @registry,
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module EntityIntrospectorSupport
+      # Tracks and handles cyclic references during entity introspection.
+      class CycleTracker
+        def initialize(entity_class, stack)
+          @entity_class = entity_class
+          @stack = stack
+        end
+
+        # Checks if the current entity class is already in the processing stack.
+        #
+        # @return [Boolean] true if a cycle is detected
+        def cyclic_reference?
+          @stack.include?(@entity_class)
+        end
+
+        # Handles a detected cycle by marking the schema with a description.
+        #
+        # @param schema [ApiModel::Schema] the schema to mark
+        # @return [ApiModel::Schema] the marked schema
+        def handle_cycle(schema)
+          schema.description ||= "Cycle detected while introspecting"
+          schema
+        end
+
+        # Executes a block while tracking the current entity in the stack.
+        #
+        # @yield the block to execute while tracking
+        # @return the result of the block
+        def with_tracking
+          @stack << @entity_class
+          yield
+        ensure
+          @stack.pop
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module EntityIntrospectorSupport
+      # Handles discriminator fields in entity inheritance for polymorphic schemas.
+      class DiscriminatorHandler
+        # Checks if an entity inherits from a parent that uses discriminator.
+        #
+        # @param entity_class [Class] the entity class to check
+        # @return [Boolean] true if parent has a discriminator field
+        def self.inherits_with_discriminator?(entity_class)
+          parent = find_parent_entity(entity_class)
+          parent && new(parent).discriminator?
+        end
+
+        # Finds the parent entity class if one exists.
+        #
+        # @param entity_class [Class] the entity class
+        # @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
+        end
+
+        def initialize(entity_class)
+          @entity_class = entity_class
+        end
+
+        # Applies discriminator field to the schema if one is defined.
+        #
+        # @param schema [ApiModel::Schema] the schema to modify
+        def apply(schema)
+          discriminator_field = find_discriminator_field
+          schema.discriminator = discriminator_field if discriminator_field
+        end
+
+        # Checks if this entity has a discriminator field.
+        #
+        # @return [Boolean] true if discriminator field exists
+        def discriminator?
+          exposures.any? do |exposure|
+            doc = exposure.documentation || {}
+            doc[:is_discriminator] || doc["is_discriminator"]
+          end
+        rescue NoMethodError
+          false
+        end
+
+        # Finds the discriminator field name from entity exposures.
+        #
+        # @return [String, nil] the discriminator field name or nil
+        def find_discriminator_field
+          exposures.each do |exposure|
+            doc = exposure.documentation || {}
+            is_discriminator = doc[:is_discriminator] || doc["is_discriminator"]
+            return exposure.key.to_s if is_discriminator
+          end
+          nil
+        end
+
+        private
+
+        # Gets the exposures defined on the entity class.
+        #
+        # @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
+          []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module EntityIntrospectorSupport
+      # Processes entity exposures and builds schemas from them.
+      #
+      class ExposureProcessor
+        include GrapeOAS::ApiModelBuilders::Concerns::OasUtilities
+
+        def initialize(entity_class, stack:, registry:)
+          @entity_class = entity_class
+          @stack = stack
+          @registry = registry
+        end
+
+        # Adds all exposures to a schema.
+        #
+        # @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
+
+        # Gets the exposures defined on the entity class.
+        #
+        # @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
+          []
+        end
+
+        # Gets the exposures defined on a parent entity.
+        #
+        # @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
+          []
+        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 = doc[:type] || doc["type"] || opts[:using]
+
+          schema = build_exposure_base_schema(type)
+          apply_exposure_properties(schema, doc)
+          apply_exposure_constraints(schema, doc)
+          schema
+        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
+          true
+        end
+
+        # Checks if an exposure is conditional.
+        #
+        # @param exposure the entity exposure
+        # @return [Boolean] true if conditional
+        def conditional?(exposure)
+          conditions = exposure.instance_variable_get(:@conditions) || []
+          !conditions.empty?
+        rescue NoMethodError
+          false
+        end
+
+        # Checks if an exposure is a merge exposure.
+        #
+        # @param exposure the entity exposure
+        # @param doc [Hash] the documentation hash
+        # @param opts [Hash] the options hash
+        # @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)
+        end
+
+        private
+
+        def add_exposure_to_schema(schema, exposure)
+          doc = exposure.documentation || {}
+          opts = exposure.instance_variable_get(:@options) || {}
+
+          if merge_exposure?(exposure, doc, opts)
+            merge_exposure_into_schema(schema, exposure, doc)
+          else
+            add_property_from_exposure(schema, exposure, doc)
+          end
+        end
+
+        def merge_exposure_into_schema(schema, exposure, doc)
+          merged_schema = 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)
+          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"]
+          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)
+          end
+        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.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=)
+        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
+          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 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 = doc[:type] || doc["type"] || opts[:using]
+          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)
+        end
+      end
+    end
+  end
+end