openapi-ruby 4.2.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f7b5b27e899e80be2470549b5a347b3e3cd9a3d3974f8d5de3842510741e252
-  data.tar.gz: d322e9f88d6164fe4f6f10203266efa88eb99a6f7b27cf0983376bc3587d2e77
+  metadata.gz: f937b3be2ac21a6d99687ca9ae2e0a625f89747c597fca146a7f04398d55cedc
+  data.tar.gz: e185d294c49caf0f33b1ad4cfc4a0512968f94ecb8f0f8184affcdd69230c94c
 SHA512:
-  metadata.gz: 1a1948211044728807f9ff02fa7a0d81af64c4d52619bbcf43895481d8309e4c949c8e40d8daff4c897d694afc53ac02fd48194fa88203bc49d5d7f102200927
-  data.tar.gz: 55a9e333eff2da6db2a8032ad3777219b8df7957f3fc49b5dafc9fc3f0cf586d35836df8439b3b40dcb09e0c2ed56b7aff6fbe7ebc67b75264bf62c1cede3cc2
+  metadata.gz: 7509404bf36980da8c58fde64c22b868e8216aaba20a13849904eedda75245f5015fece24a757e4d7c9c5b40c420554c9538afa30ab591e6b93086cce0c85928
+  data.tar.gz: 1a00f2de46c1d363686952541948bc20930bd27397a66381923c1a01262e833eedcc0e3298c3601d0c84ae288ead7a754f73825fca0d292711588823be3469bc

data/README.md

@@ -182,6 +182,37 @@ class Schemas::User
 end
 ```
 
+#### Parameter names
+
+The same setting covers parameter names, so parameters match the component keys instead of contradicting them. Declare them in snake_case — that keeps `let(:page_size)` and `params: {page_size: 20}` idiomatic Ruby — and the camelCased name is what reaches both the document and the request:
+
+```ruby
+api_path "/users/{user_id}" do
+  parameter name: :user_id, in: :path, schema: { type: :integer }
+
+  get "List posts" do
+    parameter name: :page_size, in: :query, schema: { type: :integer }
+    # ...
+  end
+end
+```
+
+```yaml
+paths:
+  /users/{userId}:            # template variables travel with the parameter names
+    parameters:
+      - name: userId
+        in: path
+    get:
+      parameters:
+        - name: pageSize
+          in: query
+```
+
+The test DSL sends what the document promises: `GET /users/7?pageSize=20`. 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.
+
+If your API takes snake_case parameters, set `config.camelize_keys = false` (or keep the parameter names camelCased in the declaration, which passes through unchanged either way).
+
 ### Scopes
 
 Assign components to scopes for multiple API specs:
@@ -253,6 +284,8 @@ rails generate openapi_ruby:component User schemas
 rails generate openapi_ruby:component BearerAuth security_schemes
 ```
 
+Files land in the first entry of `config.component_paths`, so the generator follows whatever the loader reads.
+
 ## Testing with RSpec
 
 ```ruby
@@ -621,7 +654,7 @@ Rails picks up its wiring from the engine. Every other host makes the same calls
 | `openapi_ruby:install` / `:component` generators | ✅ | — | — |
 | `openapi_permit` strong params | ✅ | — | — |
 
-Versions covered by CI: Rails 7.0–8.0, Hanami 2.3 and 3.0, Sinatra 3.2 and 4.2. Working reference apps live in [`spec/dummy`](spec/dummy), [`spec/hanami_dummy`](spec/hanami_dummy), and [`spec/sinatra_dummy`](spec/sinatra_dummy).
+Versions covered by CI: Ruby 3.2–4.0, Rails 7.0–8.0, Hanami 2.3 and 3.0, Sinatra 3.2 and 4.2. Working reference apps live in [`spec/dummy`](spec/dummy), [`spec/hanami_dummy`](spec/hanami_dummy), and [`spec/sinatra_dummy`](spec/sinatra_dummy).
 
 ### Hanami
 

data/lib/generators/openapi_ruby/component/component_generator.rb

@@ -12,11 +12,31 @@ module OpenapiRuby
 
       def create_component_file
         template "component.rb.tt",
-          File.join("app/api_components", component_type, "#{file_name}.rb")
+          File.join(component_path, component_type, "#{file_name}.rb")
       end
 
       private
 
+      # Components::Loader only looks under the configured paths, so anything
+      # written to a hardcoded app/api_components is invisible on hosts that
+      # default elsewhere (Hanami) or configure their own.
+      def component_path
+        path = OpenapiRuby.configuration.component_paths.first ||
+          Configuration.default_component_paths.first
+        relativize(path)
+      end
+
+      # An initializer may hold an absolute Rails.root.join(...) path; Thor
+      # reports the destination verbatim, and an absolute one reads as noise.
+      def relativize(path)
+        pathname = Pathname.new(path)
+        return path unless pathname.absolute?
+
+        pathname.relative_path_from(Pathname.new(destination_root)).to_s
+      rescue ArgumentError
+        path
+      end
+
       def class_name
         name.camelize
       end

data/lib/openapi_ruby/adapters/context_resolution.rb

@@ -69,7 +69,7 @@ module OpenapiRuby
       def accounted_keys(context, method)
         declared = context.path_parameters + (context.operations[method.to_s]&.parameters || [])
 
-        template_params(context) | declared.filter_map { |param| param["name"]&.to_s }
+        template_params(context) | declared.flat_map { |param| OpenapiRuby::ParameterNames.lookup_names(param) }
       end
 
       def template_params(context)

data/lib/openapi_ruby/adapters/minitest.rb

@@ -90,6 +90,7 @@ module OpenapiRuby
 
           # Build query params (exclude path params)
           query_params = params.reject { |k, _| path_param_names(context).include?(k.to_s) }
+          query_params = ParameterNames.rename_keys(query_params, operation.parameters)
 
           # Execute the request
           if body
@@ -180,7 +181,7 @@ module OpenapiRuby
         end
 
         def path_param_names(context)
-          context.path_parameters.map { |p| p["name"] }
+          context.path_parameters.flat_map { |p| ParameterNames.lookup_names(p) }
         end
 
         def resolve_base_path(schema_name)

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"
@@ -248,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

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

data/lib/openapi_ruby/testing/request_builder.rb

@@ -37,7 +37,7 @@ module OpenapiRuby
         result = {}
         query_params.each do |param|
           name = param["name"]
-          result[name] = @param_values[name] if @param_values.key?(name)
+          result[ParameterNames.wire_name(param)] = @param_values[name] if @param_values.key?(name)
         end
         result
       end

data/lib/openapi_ruby/testing/request_validator.rb

@@ -39,19 +39,30 @@ module OpenapiRuby
 
       private
 
+      # A value may arrive under the declared name or the camelized wire name,
+      # depending on whether the caller wrote it or an adapter already renamed
+      # it for the request. Both spellings resolve.
       def extract_param_value(param, params, headers, path_params)
-        name = param["name"]
+        names = ParameterNames.lookup_names(param)
 
         case param["in"]
         when "query"
-          params[name.to_sym] || params[name.to_s]
+          fetch_any(params, names)
         when "path"
-          path_params[name.to_sym] || path_params[name.to_s]
+          fetch_any(path_params, names)
         when "header"
-          headers[name] || headers[name.downcase]
+          fetch_any(headers, names.flat_map { |name| [name, name.downcase] })
         end
       end
 
+      def fetch_any(store, names)
+        names.each do |name|
+          value = store[name.to_sym] || store[name.to_s]
+          return value if value
+        end
+        nil
+      end
+
       def validate_request_body(operation, body)
         errors = []
         rb_spec = operation.request_body_definition

data/lib/openapi_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiRuby
-  VERSION = "4.2.0"
+  VERSION = "5.0.0"
 end

data/lib/openapi_ruby.rb

@@ -54,6 +54,7 @@ require_relative "openapi_ruby/components/key_transformer"
 require_relative "openapi_ruby/components/registry"
 require_relative "openapi_ruby/components/base"
 require_relative "openapi_ruby/components/loader"
+require_relative "openapi_ruby/parameter_names"
 require_relative "openapi_ruby/dsl/response_context"
 require_relative "openapi_ruby/dsl/operation_context"
 require_relative "openapi_ruby/dsl/context"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-ruby
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Morten Hartvig
@@ -106,6 +106,7 @@ files:
 - lib/openapi_ruby/middleware/response_validation.rb
 - lib/openapi_ruby/middleware/schema_resolver.rb
 - lib/openapi_ruby/minitest.rb
+- lib/openapi_ruby/parameter_names.rb
 - lib/openapi_ruby/rack_app.rb
 - lib/openapi_ruby/rake_tasks.rb
 - lib/openapi_ruby/rspec.rb