openapi-ruby 4.1.0 → 5.0.0

data/lib/openapi_ruby/adapters/rspec.rb

@@ -156,8 +156,9 @@ module OpenapiRuby
 
           headers["Accept"] ||= "application/json"
 
-          path_param_names = context.path_parameters.map { |p| p["name"] }
+          path_param_names = context.path_parameters.flat_map { |p| ParameterNames.lookup_names(p) }
           query_params = params.reject { |k, _| path_param_names.include?(k.to_s) }
+          query_params = ParameterNames.rename_keys(query_params, operation.parameters)
 
           if body
             content_type = operation.request_body_definition&.dig("content")&.keys&.first || "application/json"
@@ -192,10 +193,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 +205,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 +220,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)
@@ -237,7 +249,7 @@ module OpenapiRuby
             next if val.nil?
 
             case param["in"]
-            when "query" then params[name] = val
+            when "query" then params[ParameterNames.wire_name(param)] = val
             when "header" then headers[name] = val
             end
           end
@@ -308,19 +320,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 +340,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 +450,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 +480,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 +501,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/core/document_builder.rb

@@ -17,6 +17,7 @@ module OpenapiRuby
       end
 
       def add_path(template, operations)
+        template = ParameterNames.in_template(template)
         @paths[template] ||= {}
         @paths[template].deep_merge!(operations)
       end

data/lib/openapi_ruby/dsl/context.rb

@@ -32,7 +32,7 @@ module OpenapiRuby
       def to_openapi
         result = {}
 
-        result["parameters"] = @path_parameters if @path_parameters.any?
+        result["parameters"] = ParameterNames.parameters_for_document(@path_parameters) if @path_parameters.any?
 
         @operations.each do |verb, op|
           result[verb] = op.to_openapi

data/lib/openapi_ruby/dsl/operation_context.rb

@@ -93,7 +93,7 @@ module OpenapiRuby
         result["summary"] = @summary if @summary
         result["tags"] = @tags_list if @tags_list.any?
         result.merge!(@metadata)
-        result["parameters"] = @parameters if @parameters.any?
+        result["parameters"] = ParameterNames.parameters_for_document(@parameters) if @parameters.any?
         result["security"] = @security_list if @security_list
 
         result["requestBody"] = build_request_body if @request_body_definition

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/parameter_names.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  # Parameters are declared in snake_case so `let(:page_size)` and
+  # `params: {page_size: 1}` stay idiomatic Ruby. With `camelize_keys` on, the
+  # name that reaches the document *and* the wire is camelCased, so parameters
+  # match the component keys instead of contradicting them.
+  #
+  # Header parameters keep their declared spelling: HTTP header names are
+  # conventionally hyphenated and matched case-insensitively, so camelizing
+  # them would rename headers nobody asked to rename.
+  module ParameterNames
+    module_function
+
+    def camelize?
+      OpenapiRuby.configuration.camelize_keys
+    end
+
+    def camelize(name)
+      return name.to_s unless camelize?
+
+      Components::KeyTransformer.camelize(name)
+    end
+
+    # The name a declared parameter carries in the document and on the wire.
+    def wire_name(param)
+      name = param["name"] || param[:name]
+      return nil if name.nil?
+      return name.to_s if header?(param)
+
+      camelize(name)
+    end
+
+    # Both spellings of a declared parameter. Value lookups go through this so a
+    # caller that passes the declared name still resolves after the wire name
+    # diverged from it.
+    def lookup_names(param)
+      declared = (param["name"] || param[:name])&.to_s
+      return [] unless declared
+
+      [declared, wire_name(param)].compact.uniq
+    end
+
+    def parameters_for_document(parameters)
+      return parameters unless camelize?
+
+      parameters.map do |param|
+        wire = wire_name(param)
+        next param if wire.nil? || wire == param["name"].to_s
+
+        param.merge("name" => wire)
+      end
+    end
+
+    # `/users/{user_id}` -> `/users/{userId}`. The template variables have to
+    # travel with the parameter names: OpenAPI requires each one to be backed by
+    # a path parameter of the same name.
+    def in_template(template)
+      return template unless camelize?
+
+      template.gsub(/\{(\w+)\}/) { "{#{camelize(::Regexp.last_match(1))}}" }
+    end
+
+    # Rename the keys of a request value hash from their declared spelling to
+    # the wire spelling. Keys that match no declared parameter are left alone —
+    # undeclared params are passed through as the caller wrote them.
+    def rename_keys(values, parameters)
+      return values unless camelize?
+
+      mapping = parameters.each_with_object({}) do |param, acc|
+        declared = (param["name"] || param[:name])&.to_s
+        next unless declared
+
+        wire = wire_name(param)
+        acc[declared] = wire if wire && wire != declared
+      end
+      return values if mapping.empty?
+
+      values.each_with_object({}) do |(key, value), acc|
+        renamed = mapping[key.to_s]
+        acc[renamed.nil? ? key : renamed] = value
+      end
+    end
+
+    def header?(param)
+      (param["in"] || param[:in]).to_s == "header"
+    end
+  end
+end