openapi-ruby 4.1.0 → 4.2.0

data/lib/openapi_ruby/adapters/rspec.rb

@@ -192,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
@@ -204,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
 
@@ -219,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)
@@ -308,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
@@ -328,11 +339,11 @@ 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
@@ -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

@@ -48,9 +48,21 @@ 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

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/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

data/lib/openapi_ruby/middleware/installer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Middleware
+    # Installs the runtime validation middleware onto a Rack stack. Anything
+    # responding to #use works — Rails' `app.middleware` and Hanami's
+    # `config.middleware` share that much API, so no host branching is needed.
+    module Installer
+      module_function
+
+      def install!(stack, root: OpenapiRuby.app_root)
+        config = OpenapiRuby.configuration
+
+        return if ENV["OPENAPI_RUBY_GENERATING"]
+        return if config.request_validation == :disabled && config.response_validation == :disabled
+
+        config.schemas.each do |name, schema_config|
+          schema_path = resolve_schema_path(config, name, root)
+          next unless schema_path && File.exist?(schema_path)
+
+          resolver = SchemaResolver.new(
+            spec_path: schema_path,
+            strict_reference_validation: config.strict_reference_validation
+          )
+
+          prefix = schema_config[:prefix]
+
+          if config.request_validation != :disabled
+            stack.use RequestValidation,
+              schema_resolver: resolver,
+              mode: config.request_validation,
+              prefix: prefix
+          end
+
+          if config.response_validation != :disabled
+            stack.use ResponseValidation,
+              schema_resolver: resolver,
+              mode: config.response_validation,
+              prefix: prefix
+          end
+        end
+      end
+
+      def resolve_schema_path(config, schema_name, root)
+        ext = (config.schema_output_format == :json) ? "json" : "yaml"
+        File.join(root.to_s, config.schema_output_dir, "#{schema_name}.#{ext}")
+      end
+    end
+  end
+end

data/lib/openapi_ruby/rack_app.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module OpenapiRuby
+  # Serves the generated schema documents and the Swagger UI as a plain Rack
+  # app, for hosts with no engine to mount:
+  #
+  #   # Hanami — config/routes.rb
+  #   mount OpenapiRuby::RackApp, at: "/api-docs"
+  #
+  # Routes mirror the Rails engine's (config/routes.rb) so both hosts expose
+  # the same paths. Schema URLs are derived from SCRIPT_NAME, so the app works
+  # at any mount point.
+  #
+  # Deliberately not namespaced under OpenapiRuby::Rack: that constant would
+  # shadow the top-level ::Rack for every file in this gem.
+  class RackApp
+    SCHEMA_PATH = %r{\A/schemas/(?<name>.+)\z}
+    SCHEMA_EXTENSION = /\.(json|ya?ml)\z/
+
+    def self.call(env)
+      (@app ||= new).call(env)
+    end
+
+    def call(env)
+      request = ::Rack::Request.new(env)
+      return method_not_allowed unless request.get? || request.head?
+
+      status, headers, body = case request.path_info
+      when "", "/" then ui(request)
+      when "/schemas" then schema_index
+      when "/oauth2-redirect.html" then oauth2_redirect
+      when SCHEMA_PATH then schema(::Regexp.last_match(:name), request)
+      else not_found
+      end
+
+      # Drop the body ourselves: Rails runs Rack::Head above the engine, a bare
+      # Hanami mount has nothing between the router and here.
+      [status, headers, request.head? ? [] : body]
+    end
+
+    private
+
+    def ui(request)
+      return not_found unless OpenapiRuby.configuration.ui_enabled
+
+      html = Serving.swagger_ui_html(
+        schema_urls: schema_urls(request),
+        ui_config: OpenapiRuby.configuration.ui_config
+      )
+      respond(200, "text/html", html)
+    end
+
+    def oauth2_redirect
+      return not_found unless OpenapiRuby.configuration.ui_enabled
+
+      respond(200, "text/html", File.read(Serving.oauth2_redirect_file))
+    end
+
+    def schema_index
+      respond(200, "application/json", {schemas: Serving.schema_names}.to_json)
+    end
+
+    def schema(name, request)
+      document = Serving.schema_document(name.sub(SCHEMA_EXTENSION, ""), request: request)
+      return not_found unless document
+
+      content, content_type = document
+      respond(200, content_type, content)
+    end
+
+    def schema_urls(request)
+      OpenapiRuby.configuration.schemas.map do |name, schema_config|
+        {
+          url: "#{request.script_name}/schemas/#{name}.#{Serving.schema_format}",
+          name: schema_config.dig(:info, :title) || name.to_s
+        }
+      end
+    end
+
+    def respond(status, content_type, body, headers = {})
+      [status, {"content-type" => content_type}.merge(headers), [body]]
+    end
+
+    def not_found
+      respond(404, "application/json", {error: "Not found"}.to_json)
+    end
+
+    def method_not_allowed
+      respond(405, "application/json", {error: "Method not allowed"}.to_json, "allow" => "GET, HEAD")
+    end
+  end
+end

data/lib/openapi_ruby/rake_tasks.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rake"
+require "shellwords"
+require "openapi_ruby/generator/rake_task_support"
+
+module OpenapiRuby
+  # The Rails engine picks up lib/tasks/*.rake on its own; other hosts add
+  #
+  #   require "openapi_ruby/rake_tasks"
+  #
+  # to their Rakefile. Both routes end up here, so the task is defined once.
+  module RakeTasks
+    extend Rake::DSL
+
+    def self.install!
+      return if Rake::Task.task_defined?("openapi_ruby:generate")
+
+      namespace :openapi_ruby do
+        desc "Generate OpenAPI schema files from spec definitions and components"
+        task :generate do
+          support = OpenapiRuby::Generator::RakeTaskSupport
+          framework = ENV.fetch("FRAMEWORK") { support.detect_test_framework }.to_s
+          pattern = ENV.fetch("PATTERN") { support.default_pattern_for(framework) }
+
+          # Spawn a subprocess so the host's env defaults to "test" cleanly,
+          # just like rswag did with RSpec::Core::RakeTask.
+          script = support.generate_script(framework, pattern)
+          command = "bundle exec ruby -e #{Shellwords.escape(script)}"
+
+          puts "Generating OpenAPI schemas (#{framework})..."
+          system(support.subprocess_env, command) || abort("Schema generation failed")
+        end
+      end
+    end
+  end
+end
+
+OpenapiRuby::RakeTasks.install!