grape-oas 1.0.0

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module EntityIntrospectorSupport
+      # Handles entity inheritance and builds allOf schemas for parent-child entity relationships.
+      class InheritanceBuilder
+        def initialize(entity_class, stack:, registry:)
+          @entity_class = entity_class
+          @stack = stack
+          @registry = registry
+        end
+
+        # Finds the parent entity class if one exists.
+        #
+        # @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
+        end
+
+        # 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 && DiscriminatorHandler.new(parent).discriminator?
+        end
+
+        # Builds an inherited schema using allOf composition.
+        #
+        # @param parent_entity [Class] the parent entity class
+        # @return [ApiModel::Schema] the composed schema
+        def build_inherited_schema(parent_entity)
+          # First, ensure parent schema is built
+          parent_schema = GrapeOAS.introspectors.build_schema(parent_entity, stack: @stack, registry: @registry)
+
+          # Build child-specific properties (excluding inherited ones)
+          child_schema = build_child_only_schema(parent_entity)
+
+          # Create allOf schema with ref to parent + child properties
+          schema = ApiModel::Schema.new(
+            canonical_name: @entity_class.name,
+            all_of: [parent_schema, child_schema],
+          )
+
+          @registry[@entity_class] = schema
+          schema
+        end
+
+        private
+
+        def build_child_only_schema(parent_entity)
+          child_schema = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
+          processor = ExposureProcessor.new(@entity_class, stack: @stack, registry: @registry)
+
+          # Get parent's exposure keys to exclude
+          parent_keys = processor.parent_exposures(parent_entity).map { |e| e.key.to_s }
+
+          processor.exposures.each do |exposure|
+            next unless processor.exposed?(exposure)
+
+            name = exposure.key.to_s
+            # Skip if this is an inherited property
+            next if parent_keys.include?(name)
+
+            add_child_property(child_schema, exposure, processor)
+          end
+
+          child_schema
+        end
+
+        def add_child_property(child_schema, exposure, processor)
+          doc = exposure.documentation || {}
+          opts = exposure.instance_variable_get(:@options) || {}
+
+          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)
+
+          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
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    module EntityIntrospectorSupport
+      # Utility class for extracting properties from entity documentation hashes.
+      # All methods are stateless and can be called directly on the class.
+      class PropertyExtractor
+        class << self
+          # Extracts description from a documentation hash.
+          #
+          # @param hash [Hash] the documentation hash
+          # @return [String, nil] the description value
+          def extract_description(hash)
+            hash[:description] || hash[:desc]
+          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
+          # @param doc [Hash] the documentation hash
+          # @param opts [Hash] the options hash
+          # @return [Boolean, nil] true if this is a merge exposure
+          def extract_merge_flag(exposure, doc, opts)
+            opts[:merge] || doc[:merge] || (exposure.respond_to?(:for_merge) && exposure.for_merge)
+          end
+
+          # Applies entity-level properties to a schema.
+          #
+          # @param schema [ApiModel::Schema] the schema to modify
+          # @param doc [Hash] the entity documentation hash
+          def apply_entity_level_properties(schema, 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]
+            schema.defs = defs if defs.is_a?(Hash)
+          rescue NoMethodError
+            # Silently handle errors when schema doesn't respond to setters
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/introspectors/registry.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    # Registry for managing introspectors that can build schemas from various sources.
+    # Allows third-party gems to register custom introspectors for new schema formats.
+    #
+    # @example Registering a custom introspector
+    #   GrapeOAS.introspectors.register(MyCustomIntrospector)
+    #
+    # @example Inserting before an existing introspector
+    #   GrapeOAS.introspectors.register(HighPriorityIntrospector, before: EntityIntrospector)
+    #
+    class Registry
+      include Enumerable
+
+      def initialize
+        @introspectors = []
+      end
+
+      # Registers an introspector class.
+      #
+      # @param introspector [Class] Class that extends GrapeOAS::Introspectors::Base
+      # @param before [Class, nil] Insert before this introspector
+      # @param after [Class, nil] Insert after this introspector
+      # @return [self]
+      def register(introspector, before: nil, after: nil)
+        validate_introspector!(introspector)
+
+        if before
+          insert_before(introspector, before)
+        elsif after
+          insert_after(introspector, after)
+        else
+          @introspectors << introspector unless @introspectors.include?(introspector)
+        end
+
+        self
+      end
+
+      # Unregisters an introspector class.
+      #
+      # @param introspector [Class] The introspector to remove
+      # @return [self]
+      def unregister(introspector)
+        @introspectors.delete(introspector)
+        self
+      end
+
+      # Finds the first introspector that can handle the given subject.
+      #
+      # @param subject [Object] The object to introspect
+      # @return [Class, nil] The introspector class, or nil if none found
+      def find(subject)
+        @introspectors.find { |introspector| introspector.handles?(subject) }
+      end
+
+      # Builds a schema using the appropriate introspector.
+      #
+      # @param subject [Object] The object to introspect
+      # @param stack [Array] Recursion stack for cycle detection
+      # @param registry [Hash] Schema registry for caching
+      # @return [ApiModel::Schema, nil] The built schema, or nil if no handler found
+      def build_schema(subject, stack: [], registry: {})
+        introspector = find(subject)
+        return nil unless introspector
+
+        introspector.build_schema(subject, stack: stack, registry: registry)
+      end
+
+      # Checks if any introspector can handle the given subject.
+      #
+      # @param subject [Object] The object to check
+      # @return [Boolean]
+      def handles?(subject)
+        @introspectors.any? { |introspector| introspector.handles?(subject) }
+      end
+
+      # Iterates over all registered introspectors.
+      #
+      # @yield [introspector] Each registered introspector
+      def each(&)
+        @introspectors.each(&)
+      end
+
+      # Returns the number of registered introspectors.
+      #
+      # @return [Integer]
+      def size
+        @introspectors.size
+      end
+
+      # Clears all registered introspectors.
+      #
+      # @return [self]
+      def clear
+        @introspectors.clear
+        self
+      end
+
+      # Returns a list of registered introspectors.
+      #
+      # @return [Array<Class>]
+      def to_a
+        @introspectors.dup
+      end
+
+      private
+
+      def validate_introspector!(introspector)
+        return if introspector.respond_to?(:handles?) && introspector.respond_to?(:build_schema)
+
+        raise ArgumentError,
+              "Introspector must respond to .handles?(subject) and .build_schema(subject, stack:, registry:)"
+      end
+
+      def insert_before(introspector, target)
+        index = @introspectors.index(target)
+        if index
+          @introspectors.insert(index, introspector) unless @introspectors.include?(introspector)
+        else
+          @introspectors << introspector unless @introspectors.include?(introspector)
+        end
+      end
+
+      def insert_after(introspector, target)
+        index = @introspectors.index(target)
+        if index
+          @introspectors.insert(index + 1, introspector) unless @introspectors.include?(introspector)
+        else
+          @introspectors << introspector unless @introspectors.include?(introspector)
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/rake/oas_tasks.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "rake"
+require "rake/tasklib"
+require "json"
+
+module GrapeOAS
+  module Rake
+    # Rake tasks for generating and validating OpenAPI documentation.
+    #
+    # @example Usage in Rakefile
+    #   require 'grape_oas/rake/oas_tasks'
+    #   GrapeOAS::Rake::OasTasks.new(MyAPI)
+    #
+    # @example With options
+    #   GrapeOAS::Rake::OasTasks.new(MyAPI, schema_type: :oas31, title: "My API")
+    #
+    class OasTasks < ::Rake::TaskLib
+      attr_reader :api_class, :options
+
+      # @param api_class [Class, String] The Grape API class or its name as a string
+      # @param options [Hash] Options passed to GrapeOAS.generate
+      def initialize(api_class, **options)
+        super()
+
+        if api_class.is_a?(String)
+          @api_class_name = api_class
+        else
+          @api_class = api_class
+        end
+
+        @options = options
+        define_tasks
+      end
+
+      private
+
+      def resolved_api_class
+        @resolved_api_class ||= @api_class || @api_class_name.constantize
+      end
+
+      # Returns :environment if the task exists, otherwise an empty array
+      # This allows the tasks to work both in Rails (with :environment) and standalone
+      def environment_task
+        ::Rake::Task.task_defined?(:environment) ? :environment : []
+      end
+
+      def define_tasks
+        namespace :oas do
+          define_generate_task
+          define_validate_task
+        end
+      end
+
+      def define_generate_task
+        desc <<~DESC
+          Generate OpenAPI documentation
+          Params (usage: KEY=value):
+            output   - Output file path (default: stdout)
+            format   - Output format: json or yaml (default: json)
+            version  - OpenAPI version: oas2, oas3, oas31 (default: from options or oas3)
+        DESC
+        task generate: environment_task do
+          schema = generate_schema
+          output = format_output(schema)
+
+          if output_file
+            File.write(output_file, output)
+            $stdout.puts "OpenAPI spec written to #{output_file}"
+          else
+            $stdout.puts output
+          end
+        end
+      end
+
+      def define_validate_task
+        desc <<~DESC
+          Validate OpenAPI documentation using swagger-cli
+          Params (usage: KEY=value):
+            version  - OpenAPI version: oas2, oas3, oas31 (default: from options or oas3)
+        DESC
+        task validate: environment_task do
+          require "tempfile"
+
+          schema = generate_schema
+          output = JSON.pretty_generate(schema)
+
+          Tempfile.create(["openapi", ".json"]) do |f|
+            f.write(output)
+            f.flush
+
+            if system("which swagger-cli > /dev/null 2>&1")
+              success = system("swagger-cli validate #{f.path}")
+              exit(1) unless success
+            else
+              warn "swagger-cli not found. Install with: npm install -g @apidevtools/swagger-cli"
+              exit(1)
+            end
+          end
+        end
+      end
+
+      def generate_schema
+        schema_type = ENV.fetch("version", nil)&.to_sym || options[:schema_type] || :oas3
+        GrapeOAS.generate(app: resolved_api_class, schema_type: schema_type, **options)
+      end
+
+      def format_output(schema)
+        case output_format
+        when "yaml"
+          require "yaml"
+          schema.to_yaml
+        else
+          JSON.pretty_generate(schema)
+        end
+      end
+
+      def output_file
+        ENV.fetch("output", nil)
+      end
+
+      def output_format
+        ENV.fetch("format", "json")
+      end
+    end
+  end
+end

data/lib/grape_oas/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  VERSION = "1.0.0"
+end

data/lib/grape_oas.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "grape"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "api" => "API",
+  "grape-oas" => "GrapeOAS",
+  "grape_oas" => "GrapeOAS",
+  "oas2" => "OAS2",
+  "oas2_schema" => "OAS2Schema",
+  "oas3" => "OAS3",
+  "oas3_schema" => "OAS3Schema",
+  "oas30" => "OAS30",
+  "oas30_schema" => "OAS30Schema",
+  "oas31" => "OAS31",
+  "oas31_schema" => "OAS31Schema",
+)
+loader.ignore("#{__dir__}/grape-oas.rb")
+loader.setup
+
+# GrapeOAS generates OpenAPI specifications from Grape APIs.
+#
+# @example Basic usage
+#   schema = GrapeOAS.generate(app: MyAPI)
+#   puts JSON.pretty_generate(schema)
+#
+# @example Generate OpenAPI 2.0 (Swagger)
+#   schema = GrapeOAS.generate(app: MyAPI, schema_type: :oas2)
+#
+# @example Generate OpenAPI 3.1
+#   schema = GrapeOAS.generate(app: MyAPI, schema_type: :oas31)
+#
+module GrapeOAS
+  # Returns the version of the GrapeOAS gem.
+  #
+  # @return [String] the semantic version string
+  def version
+    OAS::VERSION
+  end
+  module_function :version
+
+  # Returns the global introspector registry.
+  #
+  # The registry manages introspectors that build schemas from various sources
+  # (e.g., Grape::Entity, Dry contracts). Third-party gems can register custom
+  # introspectors to support new schema definition formats.
+  #
+  # @return [Introspectors::Registry] the global introspector registry
+  #
+  # @example Registering a custom introspector
+  #   GrapeOAS.introspectors.register(MyCustomIntrospector)
+  #
+  # @example Inserting before an existing introspector
+  #   GrapeOAS.introspectors.register(
+  #     HighPriorityIntrospector,
+  #     before: GrapeOAS::Introspectors::EntityIntrospector
+  #   )
+  #
+  def introspectors
+    @introspectors ||= begin
+      registry = Introspectors::Registry.new
+      # Register built-in introspectors in order of precedence
+      registry.register(Introspectors::EntityIntrospector)
+      registry.register(Introspectors::DryIntrospector)
+      registry
+    end
+  end
+  module_function :introspectors
+
+  # Returns the global exporter registry.
+  #
+  # The registry manages exporters that generate OpenAPI specifications
+  # in different versions (OAS 2.0, 3.0, 3.1). Third-party gems can register
+  # custom exporters for new output formats.
+  #
+  # @return [Exporter::Registry] the global exporter registry
+  #
+  # @example Registering a custom exporter
+  #   GrapeOAS.exporters.register(:custom, MyCustomExporter)
+  #
+  # @example Using a custom exporter
+  #   schema = GrapeOAS.generate(app: MyAPI, schema_type: :custom)
+  #
+  def exporters
+    @exporters ||= begin
+      registry = Exporter::Registry.new
+      # Register built-in exporters
+      registry.register(Exporter::OAS2Schema, as: :oas2)
+      registry.register(Exporter::OAS30Schema, as: %i[oas3 oas30])
+      registry.register(Exporter::OAS31Schema, as: :oas31)
+      registry
+    end
+  end
+  module_function :exporters
+
+  # Generates an OpenAPI specification from a Grape API application.
+  #
+  # Introspects the Grape API routes, parameters, entities, and contracts
+  # to produce a complete OpenAPI specification document.
+  #
+  # @param app [Class<Grape::API>] The Grape API class to document
+  # @param schema_type [Symbol] The OpenAPI version to generate
+  #   - `:oas2` - OpenAPI 2.0 (Swagger)
+  #   - `:oas3` - OpenAPI 3.0 (default)
+  #   - `:oas31` - OpenAPI 3.1
+  # @param options [Hash] Additional options passed to the API model builder
+  # @option options [String] :title API title for the info section
+  # @option options [String] :version API version string
+  # @option options [Array<String>] :servers Server URLs (OAS3 only)
+  # @option options [Hash] :license License information
+  # @option options [Hash] :security_definitions Security scheme definitions
+  # @option options [String] :namespace Filter routes to only include paths
+  #   starting with this namespace (e.g., "users" includes /users and /users/{id})
+  #
+  # @return [Hash] The OpenAPI specification as a Hash (JSON-serializable)
+  #
+  # @example Basic generation
+  #   schema = GrapeOAS.generate(app: MyAPI)
+  #
+  # @example With custom metadata
+  #   schema = GrapeOAS.generate(
+  #     app: MyAPI,
+  #     schema_type: :oas3,
+  #     title: "My API",
+  #     version: "1.0.0"
+  #   )
+  #
+  # @example Filter by namespace
+  #   schema = GrapeOAS.generate(app: MyAPI, namespace: "users")
+  #   # Only includes paths like /users, /users/{id}, etc.
+  #
+  def generate(app:, schema_type: :oas3, **options)
+    api_model = GrapeOAS::ApiModelBuilder.new(options)
+    api_model.add_app(app)
+
+    GrapeOAS::Exporter.for(schema_type)
+                      .new(api_model: api_model.api)
+                      .generate
+  end
+  module_function :generate
+end
+
+Grape::API::Instance.extend(GrapeOAS::DocumentationExtension)