grape-oas 1.0.0

data/lib/grape_oas/exporter/oas3_schema.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "concerns/tag_builder"
+require_relative "concerns/schema_indexer"
+
+module GrapeOAS
+  module Exporter
+    class OAS3Schema
+      include Concerns::TagBuilder
+      include Concerns::SchemaIndexer
+
+      def initialize(api_model:)
+        @api = api_model
+        @ref_tracker = Set.new
+        @ref_schemas = {}
+      end
+
+      def generate
+        {
+          "openapi" => openapi_version,
+          "info" => build_info,
+          "servers" => build_servers,
+          "tags" => build_tags,
+          "paths" => OAS3::Paths.new(@api, @ref_tracker,
+                                     nullable_keyword: nullable_keyword?,
+                                     suppress_default_error_response: @api.suppress_default_error_response,).build,
+          "components" => build_components,
+          "security" => build_security
+        }.compact
+      end
+
+      private
+
+      def openapi_version
+        "3.0.0"
+      end
+
+      # Allow subclasses (e.g., OAS31Schema) to override
+      def schema_builder
+        OAS3::Schema
+      end
+
+      def build_info
+        info = {
+          "title" => @api.title,
+          "version" => @api.version
+        }
+        license = if @api.respond_to?(:license) && @api.license
+                    @api.license.dup
+                  else
+                    { "name" => Constants::Defaults::LICENSE_NAME, "url" => Constants::Defaults::LICENSE_URL }
+                  end
+        license.delete("identifier")
+        license["url"] ||= Constants::Defaults::LICENSE_URL
+        info["license"] = license
+        info
+      end
+
+      def build_servers
+        servers = Array(@api.servers).map do |srv|
+          srv.is_a?(Hash) ? srv : { "url" => srv.to_s }
+        end
+
+        servers = [{ "url" => Constants::Defaults::SERVER_URL }] if servers.empty?
+
+        servers
+      end
+
+      def build_components
+        schemas = build_schemas
+        security_schemes = build_security_schemes
+        components = {}
+        components["schemas"] = schemas if schemas.any?
+        components["securitySchemes"] = security_schemes if security_schemes&.any?
+        components
+      end
+
+      def build_schemas
+        schemas = {}
+        pending = @ref_tracker ? @ref_tracker.to_a : []
+        processed = Set.new
+
+        # Add pre-registered models to pending
+        Array(@api.registered_schemas).each do |schema|
+          pending << schema.canonical_name if schema.respond_to?(:canonical_name) && schema.canonical_name
+        end
+
+        until pending.empty?
+          canonical_name = pending.shift
+          next if processed.include?(canonical_name)
+
+          processed << canonical_name
+
+          ref_name = canonical_name.gsub("::", "_")
+          schema = find_schema_by_canonical_name(canonical_name)
+          if schema
+            schemas[ref_name] =
+              schema_builder.new(schema, @ref_tracker, nullable_keyword: nullable_keyword?).build
+          end
+          collect_refs(schema, pending) if schema
+
+          # any new refs added while building
+          next unless @ref_tracker
+
+          @ref_tracker.to_a.each do |cn|
+            pending << cn unless processed.include?(cn) || pending.include?(cn)
+          end
+        end
+
+        schemas
+      end
+
+      def build_security_schemes
+        return nil if @api.security_definitions.nil? || @api.security_definitions.empty?
+
+        @api.security_definitions
+      end
+
+      def build_security
+        return @api.security unless @api.security.nil? || @api.security.empty?
+
+        []
+      end
+
+      def nullable_keyword?
+        true
+      end
+    end
+  end
+end

data/lib/grape_oas/exporter/registry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    # Registry for managing schema exporters for different OpenAPI versions.
+    # Allows third-party gems to register custom exporters for new formats.
+    #
+    # @example Registering a custom exporter with single alias
+    #   GrapeOAS.exporters.register(MyCustomExporter, as: :custom)
+    #
+    # @example Registering with multiple aliases
+    #   GrapeOAS.exporters.register(OAS30Schema, as: [:oas3, :oas30])
+    #
+    class Registry
+      def initialize
+        @exporters = {}
+      end
+
+      # Registers an exporter class for one or more schema types.
+      #
+      # @param exporter_class [Class] The exporter class to register
+      # @param as [Symbol, Array<Symbol>] The schema type identifier(s)
+      # @return [self]
+      def register(exporter_class, as:)
+        schema_types = Array(as)
+        schema_types.each { |type| @exporters[type] = exporter_class }
+        self
+      end
+
+      # Unregisters an exporter for one or more schema types.
+      #
+      # @param schema_types [Symbol, Array<Symbol>] The schema type(s) to remove
+      # @return [self]
+      def unregister(*schema_types)
+        schema_types.flatten.each { |type| @exporters.delete(type) }
+        self
+      end
+
+      # Finds the exporter class for a given schema type.
+      #
+      # @param schema_type [Symbol] The schema type
+      # @return [Class] The exporter class
+      # @raise [ArgumentError] if no exporter is registered for the type
+      def for(schema_type)
+        exporter = @exporters[schema_type]
+        raise ArgumentError, "Unsupported schema type: #{schema_type}" unless exporter
+
+        exporter
+      end
+
+      # Checks if an exporter is registered for the given schema type.
+      #
+      # @param schema_type [Symbol] The schema type to check
+      # @return [Boolean]
+      def registered?(schema_type)
+        @exporters.key?(schema_type)
+      end
+
+      # Returns all registered schema types.
+      #
+      # @return [Array<Symbol>]
+      def schema_types
+        @exporters.keys
+      end
+
+      # Returns the number of registered exporters.
+      #
+      # @return [Integer]
+      def size
+        @exporters.size
+      end
+
+      # Clears all registered exporters.
+      #
+      # @return [self]
+      def clear
+        @exporters.clear
+        self
+      end
+    end
+  end
+end

data/lib/grape_oas/exporter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    # Returns the exporter class for the given schema type.
+    # Delegates to the global exporter registry.
+    #
+    # @param schema_type [Symbol] The type of schema (:oas2, :oas3, :oas30, :oas31)
+    # @return [Class] The exporter class for the specified schema type
+    # @raise [ArgumentError] if no exporter is registered for the type
+    def for(schema_type)
+      GrapeOAS.exporters.for(schema_type)
+    end
+    module_function :for
+  end
+end

data/lib/grape_oas/introspectors/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    # Base module that defines the interface for all introspectors.
+    # Any introspector (built-in or third-party) must implement these class methods.
+    #
+    # @example Implementing a custom introspector
+    #   class MyIntrospector
+    #     extend GrapeOAS::Introspectors::Base
+    #
+    #     def self.handles?(subject)
+    #       subject.is_a?(Class) && subject < MyResponseModel
+    #     end
+    #
+    #     def self.build_schema(subject, stack: [], registry: {})
+    #       # Build and return an ApiModel::Schema
+    #     end
+    #   end
+    #
+    #   # Register the introspector
+    #   GrapeOAS.introspectors.register(MyIntrospector)
+    #
+    module Base
+      # Checks if this introspector can handle the given subject.
+      #
+      # @param subject [Object] The object to introspect (e.g., entity class, contract)
+      # @return [Boolean] true if this introspector can handle the subject
+      def handles?(subject)
+        raise NotImplementedError, "#{self} must implement .handles?(subject)"
+      end
+
+      # Builds a schema from the given subject.
+      #
+      # @param subject [Object] The object to introspect
+      # @param stack [Array] Recursion stack for cycle detection
+      # @param registry [Hash] Schema registry for caching built schemas
+      # @return [ApiModel::Schema, nil] The built schema, or nil if not applicable
+      def build_schema(subject, stack: [], registry: {})
+        raise NotImplementedError, "#{self} must implement .build_schema(subject, stack:, registry:)"
+      end
+    end
+  end
+end

data/lib/grape_oas/introspectors/dry_introspector.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "dry_introspector_support/contract_resolver"
+require_relative "dry_introspector_support/inheritance_handler"
+require_relative "dry_introspector_support/type_schema_builder"
+
+module GrapeOAS
+  module Introspectors
+    # Introspector for Dry::Validation contracts and Dry::Schema.
+    # Extracts an ApiModel schema from contract definitions.
+    class DryIntrospector
+      extend Base
+
+      # Re-export ConstraintSet for external use
+      ConstraintSet = DryIntrospectorSupport::ConstraintExtractor::ConstraintSet
+
+      # Checks if the subject is a Dry contract or schema.
+      #
+      # @param subject [Object] The object to check
+      # @return [Boolean] true if subject is a Dry contract/schema
+      def self.handles?(subject)
+        # Check for Dry::Validation::Contract class
+        return true if dry_contract_class?(subject)
+
+        # Check for schema with types (instantiated contract or schema result)
+        return true if subject.respond_to?(:schema) && subject.schema.respond_to?(:types)
+
+        # Check for direct schema object
+        subject.respond_to?(:types)
+      end
+
+      # Builds a schema from a Dry contract or schema.
+      #
+      # @param subject [Object] Contract class, instance, or schema
+      # @param stack [Array] Recursion stack for cycle detection
+      # @param registry [Hash] Schema registry for caching
+      # @return [ApiModel::Schema, nil] The built schema
+      def self.build_schema(subject, stack: [], registry: {})
+        new(subject, stack: stack, registry: registry).build
+      end
+
+      # Legacy class method for backward compatibility.
+      # @deprecated Use build_schema instead
+      def self.build(contract, stack: [], registry: {})
+        build_schema(contract, stack: stack, registry: registry)
+      end
+
+      def self.dry_contract_class?(subject)
+        defined?(Dry::Validation::Contract) && subject.is_a?(Class) && subject < Dry::Validation::Contract
+      end
+      private_class_method :dry_contract_class?
+
+      def initialize(contract, stack: [], registry: {})
+        @contract = contract
+        @stack = stack
+        @registry = registry
+      end
+
+      def build
+        return unless contract_resolver.contract_schema.respond_to?(:types)
+
+        # Check registry cache first (like EntityIntrospector does)
+        cached = cached_schema
+        return cached if cached
+
+        parent_contract = inheritance_handler.find_parent_contract
+        return inheritance_handler.build_inherited_schema(parent_contract, type_schema_builder) if parent_contract
+
+        build_flat_schema
+      end
+
+      private
+
+      # Returns cached schema if it exists and has properties.
+      # Checks by both canonical_name (for Dry::Schema with schema_name)
+      # and contract_class (for Dry::Validation::Contract).
+      #
+      # @return [ApiModel::Schema, nil]
+      def cached_schema
+        # Try canonical_name first (for Dry::Schema objects with schema_name)
+        if contract_resolver.canonical_name
+          cached = @registry[contract_resolver.canonical_name]
+          return cached if cached && !cached.properties.empty?
+        end
+
+        # Fall back to contract_class (for Dry::Validation::Contract)
+        cached = @registry[contract_resolver.contract_class]
+        return cached if cached && !cached.properties.empty?
+
+        nil
+      end
+
+      def build_flat_schema
+        rule_constraints = DryIntrospectorSupport::ConstraintExtractor.extract(contract_resolver.contract_schema)
+        schema = ApiModel::Schema.new(
+          type: Constants::SchemaTypes::OBJECT,
+          canonical_name: contract_resolver.canonical_name,
+        )
+
+        contract_resolver.contract_schema.types.each do |name, dry_type|
+          constraints = rule_constraints[name]
+          prop_schema = type_schema_builder.build_schema_for_type(dry_type, constraints)
+          schema.add_property(name, prop_schema, required: type_schema_builder.required?(dry_type, constraints))
+        end
+
+        # Use canonical_name as registry key for schema objects (they don't have unique classes),
+        # fall back to contract_class for Contract classes
+        registry_key = contract_resolver.canonical_name || contract_resolver.contract_class
+        @registry[registry_key] = schema
+        schema
+      end
+
+      def contract_resolver
+        @contract_resolver ||= DryIntrospectorSupport::ContractResolver.new(@contract)
+      end
+
+      def inheritance_handler
+        @inheritance_handler ||= DryIntrospectorSupport::InheritanceHandler.new(
+          contract_resolver,
+          stack: @stack,
+          registry: @registry,
+        )
+      end
+
+      def type_schema_builder
+        @type_schema_builder ||= DryIntrospectorSupport::TypeSchemaBuilder.new
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module DryIntrospectorSupport
+      # Extracts typed values from Dry::Schema AST argument nodes.
+      module ArgumentExtractor
+        module_function
+
+        def extract_numeric(arg)
+          return arg if arg.is_a?(Numeric)
+          return arg[1] if arg.is_a?(Array) && arg.size == 2 && arg.first == :num
+
+          nil
+        end
+
+        def extract_range(arg)
+          return arg if arg.is_a?(Range)
+          return arg[1] if arg.is_a?(Array) && arg.first == :range
+
+          nil
+        end
+
+        def extract_list(arg)
+          return arg[1] if arg.is_a?(Array) && %i[list set].include?(arg.first)
+          return arg if arg.is_a?(Array)
+
+          nil
+        end
+
+        def extract_literal(arg)
+          return arg unless arg.is_a?(Array)
+          return arg[1] if arg.length == 2 && %i[value val literal class left right].include?(arg.first)
+          return extract_literal(arg.first) if arg.first.is_a?(Array)
+
+          arg
+        end
+
+        def extract_pattern(arg)
+          return arg.source if arg.is_a?(Regexp)
+          return arg[1].source if arg.is_a?(Array) && arg.first == :regexp && arg[1].is_a?(Regexp)
+          return arg[1] if arg.is_a?(Array) && arg.first == :regexp && arg[1].is_a?(String)
+          return arg[1].source if arg.is_a?(Array) && arg.first == :regex && arg[1].is_a?(Regexp)
+          return arg[1] if arg.is_a?(Array) && arg.first == :regex && arg[1].is_a?(String)
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module DryIntrospectorSupport
+      # Walks Dry::Schema AST nodes and extracts validation constraints.
+      #
+      # Dry::Schema and Dry::Validation use an AST representation for their rules.
+      # This walker traverses the AST and extracts constraints (enum values, min/max,
+      # nullable, etc.) into a ConstraintSet that can be applied to OpenAPI schemas.
+      #
+      # @example Walking a simple AST
+      #   walker = AstWalker.new(ConstraintSet)
+      #   constraints = walker.walk([:predicate, [:type?, [String]]])
+      #
+      class AstWalker
+        # AST tags that represent logical/structural nodes vs predicates
+        LOGIC_TAGS = %i[predicate rule and or implication not key each].freeze
+
+        # Creates a new AST walker.
+        #
+        # @param constraint_set_class [Class] the class to use for constraint aggregation
+        def initialize(constraint_set_class)
+          @constraint_set_class = constraint_set_class
+        end
+
+        # Walks an AST and extracts all constraints.
+        #
+        # @param ast [Array] the Dry::Schema AST node
+        # @return [ConstraintSet] the extracted constraints
+        def walk(ast)
+          constraints = constraint_set_class.new(unhandled_predicates: [])
+          visit(ast, constraints)
+          constraints
+        end
+
+        # Intersects multiple constraint branches (for OR logic).
+        #
+        # When handling OR branches, only constraints that apply to ALL branches
+        # should be included in the output. This method computes the intersection.
+        #
+        # @param branches [Array<ConstraintSet>] the branches to intersect
+        # @return [ConstraintSet] the intersected constraints
+        def intersect_branches(branches)
+          return branches.first if branches.size <= 1
+
+          base = branches.first
+          branches[1..].each do |b|
+            intersect_branch(base, b)
+          end
+          base
+        end
+
+        private
+
+        attr_reader :constraint_set_class
+
+        def visit(node, constraints)
+          return unless node.is_a?(Array)
+
+          tag = node[0]
+          if shorthand_predicate?(tag, node)
+            PredicateHandler.new(constraints).handle([tag, node[1]])
+            return
+          end
+          visit_tag(tag, node, constraints)
+        end
+
+        def shorthand_predicate?(tag, node)
+          tag.is_a?(Symbol) && !LOGIC_TAGS.include?(tag) && node.length == 2
+        end
+
+        def visit_tag(tag, node, constraints)
+          case tag
+          when :predicate
+            PredicateHandler.new(constraints).handle(node[1])
+          when :rule, :not, :each
+            visit(node[1], constraints)
+          when :or
+            visit_or_branch(node, constraints)
+          when :key
+            visit(node[1][1], constraints) if node[1].is_a?(Array)
+          else # :and, :implication, and any other tags
+            visit_children(node, constraints)
+          end
+        end
+
+        def visit_children(node, constraints)
+          Array(node[1]).each { |child| visit(child, constraints) }
+        end
+
+        def visit_or_branch(node, constraints)
+          branches = Array(node[1]).map { |child| branch_constraints(child) }
+          common = intersect_branches(branches)
+          ConstraintMerger.merge(constraints, common)
+        end
+
+        def branch_constraints(child)
+          c = constraint_set_class.new(unhandled_predicates: [])
+          visit(child, c)
+          c
+        end
+
+        def intersect_branch(base, other)
+          base.enum = (base.enum & other.enum) if base.enum && other.enum
+          base.min_size = intersect_min(base.min_size, other.min_size)
+          base.max_size = intersect_max(base.max_size, other.max_size)
+          base.minimum = intersect_min(base.minimum, other.minimum)
+          base.maximum = intersect_max(base.maximum, other.maximum)
+          base.exclusive_minimum &&= other.exclusive_minimum if other.exclusive_minimum == false
+          base.exclusive_maximum &&= other.exclusive_maximum if other.exclusive_maximum == false
+          base.nullable &&= other.nullable if other.nullable == false
+        end
+
+        def intersect_min(val1, val2)
+          val1 && val2 ? [val1, val2].max : nil
+        end
+
+        def intersect_max(val1, val2)
+          val1 && val2 ? [val1, val2].min : nil
+        end
+      end
+    end
+  end
+end