openapi-ruby 4.0.3 → 4.2.0

data/lib/openapi_ruby/adapters/minitest.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "openapi_ruby"
+require_relative "context_resolution"
 require "cgi"
 require "uri"
 
@@ -12,6 +13,21 @@ module OpenapiRuby
           base.extend ClassMethods
           base.class_attribute :_openapi_contexts, default: []
           base.class_attribute :_openapi_schema_name, default: nil
+
+          install_rack_test!(base)
+        end
+
+        # On Rails the test class already inherits ActionDispatch's integration
+        # helpers. Every other host drives requests through rack-test, and the
+        # class defines `app` itself.
+        def self.install_rack_test!(base)
+          return if OpenapiRuby.rails_host?
+          return if base.method_defined?(:last_response)
+
+          require "rack/test"
+          base.include ::Rack::Test::Methods
+        rescue LoadError
+          nil
         end
 
         module ClassMethods
@@ -20,16 +36,30 @@ module OpenapiRuby
           end
 
           def api_path(template, &block)
+            guard_single_api_path!(template)
+
             context = OpenapiRuby::DSL::Context.new(template, schema_name: _openapi_schema_name)
             context.instance_eval(&block) if block
             self._openapi_contexts = _openapi_contexts + [context]
             OpenapiRuby::DSL::MetadataStore.register(context)
             context
           end
+
+          private def guard_single_api_path!(template)
+            return unless OpenapiRuby.configuration.single_api_path_per_class
+
+            existing = _openapi_contexts.first
+            return if existing.nil?
+
+            raise OpenapiRuby::MultipleApiPaths,
+              "#{name || self} already declares api_path #{existing.path_template.inspect}; " \
+              "declare #{template.inspect} in its own class."
+          end
         end
 
-        def assert_api_response(method, expected_status, params: {}, headers: {}, body: nil, path_params: {}, &block)
-          context = find_context_for(method, path_params)
+        def assert_api_response(method, expected_status, params: {}, headers: {}, body: nil, path_params: {},
+          api_path: nil, &block)
+          context = find_context_for(method, path_params, params, expected_status, api_path)
           raise OpenapiRuby::Error, "No api_path defined for #{method.upcase} in #{self.class}" unless context
 
           operation = context.operations[method.to_s]
@@ -96,18 +126,18 @@ module OpenapiRuby
             assert req_errors.empty?, "Request validation failed:\n#{req_errors.join("\n")}"
           end
 
-          send(method, path, **request_args)
+          openapi_transport.dispatch(method, path, **request_args)
 
           # Validate response
-          assert_equal expected_status, response.status,
-            "Expected status #{expected_status}, got #{response.status}\nResponse body: #{response.body}"
+          assert_equal expected_status, openapi_response.status,
+            "Expected status #{expected_status}, got #{openapi_response.status}\nResponse body: #{openapi_response.body}"
 
           if response_ctx.schema_definition
             validator = Testing::ResponseValidator.new
             body_data = parse_response_body
             errors = validator.validate(
               response_body: body_data,
-              status_code: response.status,
+              status_code: openapi_response.status,
               response_context: response_ctx
             )
             assert errors.empty?, "Response validation failed:\n#{errors.join("\n")}"
@@ -121,20 +151,24 @@ module OpenapiRuby
           parse_response_body
         end
 
-        private
+        # The seam between the DSL and the host's request API. Public so specs
+        # that drive requests themselves (rate limiting, pagination loops) can
+        # reach the same dispatcher and response the assertions use.
+        def openapi_transport
+          @openapi_transport ||= Testing::Transport.for(self)
+        end
 
-        def find_context_for(method, path_params)
-          has_path_params = path_params.any?
+        def openapi_response
+          openapi_transport.response
+        end
 
-          self.class._openapi_contexts.find do |ctx|
-            next false unless ctx.operations.key?(method.to_s)
+        private
 
-            if has_path_params
-              ctx.path_template.include?("{")
-            else
-              !ctx.path_template.include?("{")
-            end
-          end
+        def find_context_for(method, path_params, params, expected_status, api_path)
+          OpenapiRuby::Adapters::ContextResolution.resolve(
+            self.class._openapi_contexts, method, path_params,
+            params: params, expected_status: expected_status, api_path: api_path, owner: self.class
+          )
         end
 
         def expand_path(template, params)
@@ -214,11 +248,11 @@ module OpenapiRuby
         end
 
         def parse_response_body
-          return nil if response.body.empty?
+          return nil if openapi_response.body.empty?
 
-          JSON.parse(response.body)
+          JSON.parse(openapi_response.body)
         rescue JSON::ParserError
-          response.body
+          openapi_response.body
         end
       end
 

data/lib/openapi_ruby/adapters/rspec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "openapi_ruby"
+require_relative "context_resolution"
 require "cgi"
 require "uri"
 
@@ -21,8 +22,11 @@ module OpenapiRuby
           schema_name = metadata[:openapi_schema_name]
           context = DSL::Context.new(template, schema_name: schema_name)
           context.instance_eval(&block) if block
-          metadata[:openapi_api_contexts] ||= []
-          metadata[:openapi_api_contexts] << context
+          # Replace rather than push: RSpec copies parent metadata into child
+          # groups by reference, so mutating the array in place would leak this
+          # declaration back up to the parent and sideways to its siblings.
+          # Building a new one is what makes a nested describe an actual scope.
+          metadata[:openapi_api_contexts] = (metadata[:openapi_api_contexts] || []) + [context]
           DSL::MetadataStore.register(context)
           context
         end
@@ -123,9 +127,10 @@ module OpenapiRuby
         # Minitest-style assertion: looks up the api_path context, makes the
         # request, validates the response status + body, then yields to the
         # block for additional expectations.
-        def assert_api_response(method, expected_status, params: {}, headers: {}, body: nil, path_params: {}, &block)
+        def assert_api_response(method, expected_status, params: {}, headers: {}, body: nil, path_params: {},
+          api_path: nil, &block)
           meta = ::RSpec.current_example.metadata
-          context = find_api_context_for(meta, method, path_params)
+          context = find_api_context_for(meta, method, path_params, params, expected_status, api_path)
           raise OpenapiRuby::Error, "No api_path defined for #{method.upcase} in this example group" unless context
 
           operation = context.operations[method.to_s]
@@ -187,10 +192,10 @@ module OpenapiRuby
             raise "Request validation failed:\n#{req_errors.join("\n")}" unless req_errors.empty?
           end
 
-          send(method, path, **request_args)
+          openapi_transport.dispatch(method, path, **request_args)
 
-          unless response.status == expected_status
-            raise "Expected status #{expected_status}, got #{response.status}\nResponse body: #{response.body}"
+          unless openapi_response.status == expected_status
+            raise "Expected status #{expected_status}, got #{openapi_response.status}\nResponse body: #{openapi_response.body}"
           end
 
           if response_ctx.schema_definition
@@ -199,11 +204,11 @@ module OpenapiRuby
             )
             errors = validator.validate(
               response_body: parsed_response_body,
-              status_code: response.status,
+              status_code: openapi_response.status,
               response_context: response_ctx
             )
             unless errors.empty?
-              raise "Response body validation failed:\n#{errors.join("\n")}\nResponse body: #{response.body}"
+              raise "Response body validation failed:\n#{errors.join("\n")}\nResponse body: #{openapi_response.body}"
             end
           end
 
@@ -214,6 +219,17 @@ module OpenapiRuby
           parsed_response_body
         end
 
+        # The seam between the DSL and the host's request API. Public so specs
+        # that drive requests themselves (rate limiting, pagination loops) can
+        # reach the same dispatcher and response the assertions use.
+        def openapi_transport
+          @openapi_transport ||= Testing::Transport.for(self)
+        end
+
+        def openapi_response
+          openapi_transport.response
+        end
+
         # submit_openapi_request is public so specs can call it directly
         # (e.g., for rate limiting tests that need multiple requests)
         def submit_openapi_request(metadata)
@@ -303,19 +319,19 @@ module OpenapiRuby
             raise "Request validation failed:\n#{req_errors.join("\n")}" unless req_errors.empty?
           end
 
-          send(method.to_sym, path, **request_args)
+          openapi_transport.dispatch(method, path, **request_args)
         end
 
         def assert_openapi_response(metadata)
           response_ctx = find_in_metadata(metadata, :openapi_response)
 
           expected_status = response_ctx.status_code.to_i
-          actual_status = response.status
+          actual_status = openapi_response.status
 
           unless actual_status == expected_status
             raise "Response validation failed:\n" \
               "Expected status #{expected_status}, got #{actual_status}\n" \
-              "Response body: #{response.body}"
+              "Response body: #{openapi_response.body}"
           end
 
           if response_ctx.schema_definition
@@ -323,30 +339,25 @@ module OpenapiRuby
             validator = Testing::ResponseValidator.new(OpenapiRuby::Adapters::RSpec.validation_document_for(schema_name))
             errors = validator.validate(
               response_body: parsed_response_body,
-              status_code: response.status,
+              status_code: openapi_response.status,
               response_context: response_ctx
             )
             unless errors.empty?
-              raise "Response body validation failed:\n#{errors.join("\n")}\nResponse body: #{response.body}"
+              raise "Response body validation failed:\n#{errors.join("\n")}\nResponse body: #{openapi_response.body}"
             end
           end
         end
 
         private
 
-        def find_api_context_for(metadata, method, path_params)
+        def find_api_context_for(metadata, method, path_params, params, expected_status, api_path)
           contexts = find_in_metadata(metadata, :openapi_api_contexts) || []
-          has_path_params = path_params.any?
-
-          contexts.find do |ctx|
-            next false unless ctx.operations.key?(method.to_s)
 
-            if has_path_params
-              ctx.path_template.include?("{")
-            else
-              !ctx.path_template.include?("{")
-            end
-          end
+          OpenapiRuby::Adapters::ContextResolution.resolve(
+            contexts, method, path_params,
+            params: params, expected_status: expected_status, api_path: api_path,
+            owner: metadata[:full_description] || "this example group"
+          )
         end
 
         def expand_path(template, params)
@@ -438,10 +449,10 @@ module OpenapiRuby
         end
 
         def parsed_response_body
-          return nil if response.body.empty?
-          JSON.parse(response.body)
+          return nil if openapi_response.body.empty?
+          JSON.parse(openapi_response.body)
         rescue JSON::ParserError
-          response.body
+          openapi_response.body
         end
       end
 
@@ -468,6 +479,20 @@ module OpenapiRuby
         end
       end
 
+      # Every host but Rails drives requests through rack-test. Hanami also
+      # gets a default `app`; elsewhere (Sinatra, Roda, bare Rack) there is no
+      # convention for which app is under test, so the suite defines it.
+      def self.install_rack_test!(config, app_module: nil)
+        require "rack/test"
+
+        config.include ::Rack::Test::Methods, type: :openapi
+        config.include app_module, type: :openapi if app_module
+      rescue LoadError
+        # No rack-test in the bundle. Testing::Transport raises with setup
+        # instructions if a spec then tries to issue a request.
+        nil
+      end
+
       def self.install!
         ::RSpec.configure do |config|
           config.extend ExampleGroupHelpers, type: :openapi
@@ -475,6 +500,11 @@ module OpenapiRuby
 
           if defined?(::RSpec::Rails)
             config.include ::RSpec::Rails::RequestExampleGroup, type: :openapi
+          elsif OpenapiRuby.hanami_host?
+            require "openapi_ruby/hanami"
+            OpenapiRuby::Hanami.install_rspec!(config)
+          else
+            install_rack_test!(config)
           end
 
           # Schema writing is handled by the rake task (openapi_ruby:generate),

data/lib/openapi_ruby/components/loader.rb

@@ -11,6 +11,7 @@ module OpenapiRuby
       end
 
       def load!
+        warn_about_autoloaded_paths!
         define_namespace_modules!
         load_component_files!
         @@loaded = true # rubocop:disable Style/ClassVars
@@ -60,6 +61,20 @@ module OpenapiRuby
 
       private
 
+      # A component under Hanami's app/ directory loads fine here (we require
+      # the file directly) but Zeitwerk expects that file to define a deeper,
+      # app-namespaced constant — so the mismatch only surfaces on eager load
+      # in production.
+      def warn_about_autoloaded_paths!
+        return unless OpenapiRuby.hanami_host?
+
+        offending = @paths.select { |path| path.to_s.match?(%r{(\A|/)app/}) }
+        return if offending.empty?
+
+        warn "[openapi_ruby] component_paths #{offending.inspect} sit under Hanami's autoloaded " \
+          "app/ directory. Move them outside it (e.g. config/api_components) to avoid Zeitwerk conflicts."
+      end
+
       def define_namespace_modules!
         @paths.each do |path|
           expanded = File.expand_path(path)

data/lib/openapi_ruby/configuration.rb

@@ -18,6 +18,12 @@ module OpenapiRuby
     # Middleware (runtime validation)
     attr_accessor :request_validation, :response_validation, :coerce_params
 
+    # Style 2 only: require each test class to declare a single api_path.
+    # Off by default — resolution handles more than one path per class, so this
+    # is for suites that want the convention enforced anyway.
+    # See Adapters::ContextResolution for how a request is matched.
+    attr_accessor :single_api_path_per_class
+
     # Test DSL: validate that requests match the declared operation before sending.
     # Enabled by default; set to false to disable.
     attr_accessor :test_request_validation
@@ -42,15 +48,28 @@ module OpenapiRuby
     # UI (optional)
     attr_accessor :ui_enabled, :ui_config
 
+    RAILS_COMPONENT_PATHS = ["app/api_components"].freeze
+
+    # Hanami's Zeitwerk owns every constant under app/ and expects
+    # app/api_components/schemas/user.rb to define a deeper constant than
+    # Components::Loader's plain require does, so the Hanami default keeps
+    # components outside its autoload roots.
+    HANAMI_COMPONENT_PATHS = ["config/api_components"].freeze
+
+    def self.default_component_paths
+      (OpenapiRuby.hanami_host? ? HANAMI_COMPONENT_PATHS : RAILS_COMPONENT_PATHS).dup
+    end
+
     def initialize
       @schemas = {}
-      @component_paths = ["app/api_components"]
+      @component_paths = self.class.default_component_paths
       @component_scope_paths = {}
       @camelize_keys = true
       @request_validation = :disabled
       @response_validation = :disabled
       @coerce_params = true
       @test_request_validation = true
+      @single_api_path_per_class = false
       @schema_output_dir = "openapi"
       @schema_output_format = :yaml
       @ui_enabled = false

data/lib/openapi_ruby/engine.rb

@@ -5,44 +5,7 @@ module OpenapiRuby
     isolate_namespace OpenapiRuby
 
     initializer "openapi_ruby.middleware" do |app|
-      config = OpenapiRuby.configuration
-
-      next if ENV["OPENAPI_RUBY_GENERATING"]
-
-      if config.request_validation != :disabled || config.response_validation != :disabled
-        config.schemas.each do |name, schema_config|
-          schema_path = resolve_schema_path(config, name)
-          next unless schema_path && File.exist?(schema_path)
-
-          resolver = Middleware::SchemaResolver.new(
-            spec_path: schema_path,
-            strict_reference_validation: config.strict_reference_validation
-          )
-
-          prefix = schema_config[:prefix]
-
-          if config.request_validation != :disabled
-            app.middleware.use Middleware::RequestValidation,
-              schema_resolver: resolver,
-              mode: config.request_validation,
-              prefix: prefix
-          end
-
-          if config.response_validation != :disabled
-            app.middleware.use Middleware::ResponseValidation,
-              schema_resolver: resolver,
-              mode: config.response_validation,
-              prefix: prefix
-          end
-        end
-      end
-    end
-
-    private
-
-    def resolve_schema_path(config, schema_name)
-      ext = (config.schema_output_format == :json) ? "json" : "yaml"
-      Rails.root.join(config.schema_output_dir, "#{schema_name}.#{ext}").to_s
+      Middleware::Installer.install!(app.middleware)
     end
   end
 end

data/lib/openapi_ruby/errors.rb

@@ -14,6 +14,13 @@ module OpenapiRuby
     end
   end
 
+  # Raised when a Style 2 request matches more than one declared api_path.
+  class AmbiguousApiPath < Error; end
+
+  # Raised when a class declares a second api_path and
+  # `config.single_api_path_per_class` is on.
+  class MultipleApiPaths < Error; end
+
   class SchemaValidationError < Error
     attr_reader :validation_errors
 

data/lib/openapi_ruby/generator/rake_task_support.rb

@@ -24,6 +24,41 @@ module OpenapiRuby
         end
       end
 
+      # Which framework hosts the app being generated for. Detected from the
+      # filesystem as well as loaded constants: the rake process has not booted
+      # the app yet. Hanami keeps its app class in config/app.rb where Rails
+      # uses config/application.rb; a config.ru with neither is a Rack app
+      # (Sinatra, Roda, bare Rack).
+      def detect_host
+        # Files describe the app being generated for; loaded constants only say
+        # what the Rakefile happened to require, which in a mixed bundle can be
+        # either framework.
+        return "rails" if File.exist?("config/application.rb")
+        return "hanami" if File.exist?("config/app.rb")
+        return "rack" if File.exist?("config.ru")
+
+        OpenapiRuby.host.to_s
+      end
+
+      # Environment variables the host reads to decide it is running under test.
+      # Sinatra takes APP_ENV first and falls back to RACK_ENV; other Rack apps
+      # read one or the other, so a Rack host gets both.
+      HOST_ENV_VARS = {
+        "rails" => ["RAILS_ENV"],
+        "hanami" => ["HANAMI_ENV"],
+        "rack" => ["APP_ENV", "RACK_ENV"]
+      }.freeze
+
+      # Env for the generation subprocess: the host's own environment variables
+      # plus the flag that tells the gem it is generating rather than serving.
+      def subprocess_env(host = detect_host)
+        env = HOST_ENV_VARS.fetch(host, HOST_ENV_VARS["rails"]).to_h do |var|
+          [var, ENV.fetch(var, "test")]
+        end
+
+        env.merge("OPENAPI_RUBY_GENERATING" => "true")
+      end
+
       def default_pattern_for(framework)
         case framework
         when "rspec" then "spec/**/*_spec.rb"
@@ -76,13 +111,20 @@ module OpenapiRuby
 
       # Loads both adapters and both file globs in one process. Useful
       # during a phased RSpec → Minitest migration where the suite
-      # holds both DSL styles. Consumers should guard
+      # holds both DSL styles. Consumers can guard
       # `require "rails/test_help"` and `require "rspec/rails"` in
       # their test helpers with `unless OpenapiRuby.schema_generating?`
       # so the two test frameworks don't both register Rails lazy
       # hooks in the same process — only the DSL needs to be live for
       # schema generation.
       #
+      # Guarding is per-helper and optional: a suite that references
+      # what the guarded require defines at *load* time (shared
+      # examples, `fixtures :all`, `include Devise::Test::...` in a
+      # class body) fails to load those files at all, which is worse
+      # than the hook conflict. Such a helper stays unguarded and the
+      # pattern narrows instead.
+      #
       # Each glob runs with its own framework's directory at the head
       # of $LOAD_PATH so the typical `require "openapi_helper"` /
       # `require "rails_helper"` / `require "test_helper"` resolves

data/lib/openapi_ruby/hanami.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "openapi_ruby"
+
+module OpenapiRuby
+  # Hanami 2 integration. Rails receives this wiring from the engine's
+  # initializer and from rspec-rails; Hanami has no engines, so the host app
+  # makes the calls itself.
+  #
+  # ::Hanami is spelled with leading colons throughout — inside this namespace
+  # a bare `Hanami` would resolve to OpenapiRuby::Hanami.
+  module Hanami
+    # Included into :openapi example groups so rack-test knows which app to
+    # drive. A `let(:app)` in the suite takes precedence over this.
+    module RackTestApp
+      def app
+        ::Hanami.app
+      end
+    end
+
+    module_function
+
+    # Mounts the runtime validation middleware. In config/app.rb, after
+    # requiring the file that holds your OpenapiRuby.configure block:
+    #
+    #   module MyApp
+    #     class App < Hanami::App
+    #       OpenapiRuby::Hanami.install_middleware!(config)
+    #     end
+    #   end
+    #
+    # Takes the app config (preferred — it carries the root) or a bare
+    # middleware stack.
+    def install_middleware!(config, root: nil)
+      stack = config.respond_to?(:middleware) ? config.middleware : config
+      root ||= config_root(config) || OpenapiRuby.app_root
+
+      Middleware::Installer.install!(stack, root: root)
+    end
+
+    # Wires rack-test into :openapi example groups. Called for you by
+    # `require "openapi_ruby/rspec"`; exposed for suites that configure RSpec
+    # by hand.
+    def install_rspec!(rspec_config = nil)
+      if rspec_config
+        Adapters::RSpec.install_rack_test!(rspec_config, app_module: RackTestApp)
+      else
+        ::RSpec.configure { |config| Adapters::RSpec.install_rack_test!(config, app_module: RackTestApp) }
+      end
+    end
+
+    def config_root(config)
+      root = config.respond_to?(:root) ? config.root : nil
+      root unless root.to_s.empty?
+    end
+
+    # Requiring this file declares the host, so the component default no longer
+    # depends on ::Hanami being loaded before the configuration object was
+    # built. Only a pristine default is replaced.
+    def apply_component_path_default!
+      config = OpenapiRuby.configuration
+      return unless config.component_paths == Configuration::RAILS_COMPONENT_PATHS
+
+      config.component_paths = Configuration::HANAMI_COMPONENT_PATHS.dup
+    end
+  end
+end
+
+OpenapiRuby::Hanami.apply_component_path_default!

data/lib/openapi_ruby/host.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  class << self
+    # Which framework the gem is running inside. Rails wins a tie: an app with
+    # both constants loaded is a Rails app that happens to have another
+    # framework's gems in the bundle. :rack covers Sinatra, Roda, and bare Rack
+    # — anything whose only shared surface is the Rack SPEC.
+    def host
+      if defined?(::Rails)
+        :rails
+      elsif defined?(::Hanami)
+        :hanami
+      else
+        :rack
+      end
+    end
+
+    def rails_host?
+      host == :rails
+    end
+
+    def hanami_host?
+      host == :hanami
+    end
+
+    def rack_host?
+      host == :rack
+    end
+
+    # Application root, used to resolve the configured (relative)
+    # schema_output_dir. Falls back to the working directory: a bare Rack app
+    # has no root of its own, and the generation subprocess loads test files
+    # without booting an app at all.
+    def app_root
+      root = if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+        ::Rails.root
+      elsif hanami_booted?
+        ::Hanami.app.root
+      else
+        Dir.pwd
+      end
+
+      root.to_s
+    end
+
+    private
+
+    def hanami_booted?
+      defined?(::Hanami) && ::Hanami.respond_to?(:app?) && ::Hanami.app?
+    end
+  end
+end