openapi-ruby 3.0.3 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f135ed1b9a07f225cf01191cb278cd1eb62188369613e41b86df80dcbd147639
-  data.tar.gz: '008fe467062f636c4400f2dd65fa40cd09c32d6087d4c1207c9ce2667a9afc85'
+  metadata.gz: 953f7f56ecdec3d8ee0f1f1261e49328e53d0aab5041b43f47a6e1138a2e880f
+  data.tar.gz: bec8a51340348604307f17791824d9327e7ceee7b58a8f35533ef7036c12156f
 SHA512:
-  metadata.gz: fddba781e5ca09c19f5766c5b708b0408c4b0c199663f4cba23b8e1959535283f75a1b6e5550bc4defc7bbabc07442c16ad66374b7e93bebd432d29dadfe93f8
-  data.tar.gz: 67b1ef59d47959496cfb4b33ac76f3e73d961d0645bec2ae2cbc5c693e4fbb4a4d2d9121bef3f39c2840c6bf50500f8a8acead89cd91e7a5893312ccd7798db9
+  metadata.gz: c62b49da036fe1dbb27b3f7ce2937a044427ea89ded288bdab1c33dab6fc041e31c89ecb75fd2e2419731cd0f803428baed9ed5152cdf01d7cd77b42b004642e
+  data.tar.gz: 5e2bbbcf02c286120207fc06a9f86c66b2618c9766a78b4b94c215641d0c2a5173aa4c45705e4fd2e6ed909271c63000a65182d159f22f3d716a4742dcbc6bae

data/README.md

@@ -63,7 +63,6 @@ OpenapiRuby.configure do |config|
   config.camelize_keys = true
   config.schema_output_dir = "swagger"
   config.schema_output_format = :yaml
-  config.validate_responses_in_tests = true
 
   # Runtime middleware (disabled by default)
   config.request_validation = :disabled   # :enabled, :disabled, :warn_only

data/lib/generators/openapi_ruby/install/templates/initializer.rb.tt

@@ -20,9 +20,6 @@ OpenapiRuby.configure do |config|
   config.schema_output_dir = "swagger"
   config.schema_output_format = :yaml
 
-  # Validate response bodies in tests against defined schemas
-  config.validate_responses_in_tests = true
-
   # Runtime request/response validation middleware
   # Options: :disabled, :enabled, :warn_only
   config.request_validation = :disabled

data/lib/openapi_ruby/adapters/minitest.rb

@@ -87,7 +87,7 @@ module OpenapiRuby
           assert_equal expected_status, response.status,
             "Expected status #{expected_status}, got #{response.status}\nResponse body: #{response.body}"
 
-          if OpenapiRuby.configuration.validate_responses_in_tests && response_ctx.schema_definition
+          if response_ctx.schema_definition
             validator = Testing::ResponseValidator.new
             body_data = parse_response_body
             errors = validator.validate(

data/lib/openapi_ruby/adapters/rspec.rb

@@ -26,7 +26,6 @@ module OpenapiRuby
           define_method(method) do |summary = nil, &block|
             path_ctx = metadata[:openapi_path_context]
             op_context = DSL::OperationContext.new(method, summary)
-            path_ctx.path_parameters.each { |p| op_context.parameter(p) }
             path_ctx.operations[method.to_s] = op_context
 
             describe "#{method.to_s.upcase} #{path_ctx.path_template}" do
@@ -118,6 +117,7 @@ module OpenapiRuby
           # Merge individual parameter let values
           operation&.parameters&.each do |param|
             name = param["name"]
+            next unless name
             val = resolve_let(name.to_sym)
             next if val.nil?
 
@@ -144,6 +144,12 @@ module OpenapiRuby
           accept = resolve_let(:Accept)
           headers["Accept"] = accept || "application/json"
 
+          # Always append query params to the URL so the middleware sees them
+          # (Rails sends params as request body for non-GET methods).
+          if params.any?
+            path = "#{path}?#{Rack::Utils.build_nested_query(params)}"
+          end
+
           if body
             content_type = operation&.request_body_definition&.dig("content")&.keys&.first || "application/json"
             request_args = if content_type.include?("form-data") || content_type.include?("x-www-form-urlencoded")
@@ -154,13 +160,8 @@ module OpenapiRuby
                 headers: headers.merge("Content-Type" => content_type)
               }
             end
-            # Append query params to path when body is present
-            if params.any?
-              query_string = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
-              path = "#{path}?#{query_string}"
-            end
           else
-            request_args = {params: params, headers: headers}
+            request_args = {headers: headers}
           end
 
           send(method.to_sym, path, **request_args)
@@ -177,6 +178,19 @@ module OpenapiRuby
               "Expected status #{expected_status}, got #{actual_status}\n" \
               "Response body: #{response.body}"
           end
+
+          if response_ctx.schema_definition
+            schema_name = find_in_metadata(metadata, :openapi_schema_name)
+            validator = Testing::ResponseValidator.new(OpenapiRuby::Adapters::RSpec.validation_document_for(schema_name))
+            errors = validator.validate(
+              response_body: parsed_response_body,
+              status_code: response.status,
+              response_context: response_ctx
+            )
+            unless errors.empty?
+              raise "Response body validation failed:\n#{errors.join("\n")}\nResponse body: #{response.body}"
+            end
+          end
         end
 
         private
@@ -269,6 +283,29 @@ module OpenapiRuby
         end
       end
 
+      # Build the OpenAPI document hash for a given schema name and cache it.
+      # Used by response body validation so $ref schemas can be resolved.
+      def self.validation_document_for(schema_name)
+        return nil unless schema_name
+
+        key = schema_name.to_sym
+        @validation_documents ||= {}
+        @validation_documents[key] ||= begin
+          config = OpenapiRuby.configuration
+          schema_config = config.schemas[key] || config.schemas[schema_name.to_s]
+          return nil unless schema_config
+
+          builder = OpenapiRuby::Core::DocumentBuilder.new(schema_config)
+          OpenapiRuby::DSL::MetadataStore.contexts_for(schema_name).each do |context|
+            builder.add_path(context.path_template, context.to_openapi)
+          end
+          scope = schema_config[:component_scope]
+          loader = OpenapiRuby::Components::Loader.new(scope: scope)
+          builder.merge_components(loader.to_openapi_hash)
+          builder.build.data
+        end
+      end
+
       def self.install!
         ::RSpec.configure do |config|
           config.extend ExampleGroupHelpers, type: :openapi

data/lib/openapi_ruby/components/loader.rb

@@ -13,10 +13,12 @@ module OpenapiRuby
       def load!
         define_namespace_modules!
         load_component_files!
+        @@loaded = true # rubocop:disable Style/ClassVars
         self
       end
 
       def to_openapi_hash
+        ensure_loaded!
         Registry.instance.to_openapi_hash(scope: @scope)
       end
 
@@ -158,6 +160,11 @@ module OpenapiRuby
           if inferred_scope == :shared
             klass._component_scopes = []
             klass._component_scopes_explicitly_set = true
+          elsif inferred_scope.is_a?(Array)
+            Registry.instance.unregister(klass)
+            klass._component_scopes = inferred_scope
+            klass._component_scopes_explicitly_set = true
+            Registry.instance.register(klass)
           else
             Registry.instance.unregister(klass)
             klass._component_scopes = [inferred_scope]
@@ -181,14 +188,25 @@ module OpenapiRuby
 
       def infer_scope(relative_path, scope_paths)
         scope_paths.sort_by { |prefix, _| -prefix.length }.each do |prefix, scope|
-          return scope&.to_sym if relative_path.start_with?("#{prefix}/")
+          if relative_path.start_with?("#{prefix}/")
+            return scope.is_a?(Array) ? scope.map(&:to_sym) : scope&.to_sym
+          end
         end
         nil
       end
 
       def filter_type(type)
+        ensure_loaded!
         to_openapi_hash[type.to_s] || {}
       end
+
+      @@loaded = false # rubocop:disable Style/ClassVars
+
+      def ensure_loaded!
+        return if @@loaded
+
+        load!
+      end
     end
   end
 end

data/lib/openapi_ruby/components/registry.rb

@@ -89,16 +89,18 @@ module OpenapiRuby
 
       def to_openapi_hash(scope: nil)
         result = {}
+        # Track which components are scope-specific vs multi-scope/shared
+        # so scope-specific ones take precedence on name collisions.
+        specificity = {}
+
         @components.each do |type, components|
           type_key = type.to_s
           result[type_key] = {}
+          specificity[type_key] = {}
+
           components.each_value do |klass|
             next if klass._schema_hidden
-            # When filtering by scope:
-            # - Components with matching scope: included
-            # - Components explicitly marked as shared (empty scopes + explicitly_set): included
-            # - Components with non-matching scope: excluded
-            # - Components with no scope assigned (empty scopes + NOT explicitly_set): excluded
+
             if scope
               if klass._component_scopes.empty?
                 next unless klass._component_scopes_explicitly_set
@@ -107,7 +109,16 @@ module OpenapiRuby
               end
             end
 
-            result[type_key][klass.component_name] = klass.to_openapi
+            name = klass.component_name
+            is_specific = klass._component_scopes.length == 1 && klass._component_scopes.include?(scope)
+
+            # Scope-specific components take precedence over shared/multi-scope
+            if specificity[type_key][name] && !is_specific
+              next
+            end
+
+            result[type_key][name] = klass.to_openapi
+            specificity[type_key][name] = is_specific
           end
           result.delete(type_key) if result[type_key].empty?
         end

data/lib/openapi_ruby/configuration.rb

@@ -9,46 +9,51 @@ module OpenapiRuby
     # Components
     attr_accessor :component_paths
     attr_accessor :component_scope_paths
-    attr_accessor :camelize_keys, :key_transform, :response_validation, :strict_query_params,
-      :coerce_params, :error_handler, :schema_output_format, :validate_responses_in_tests, :ui_path, :ui_config, :coverage_report_path
-    attr_accessor :strict_reference_validation
+
+    # Output / formatting
+    attr_accessor :camelize_keys, :schema_output_format, :schema_output_dir
     attr_accessor :auto_validation_error_response
     attr_accessor :validation_error_schema
 
     # Middleware (runtime validation)
-    attr_accessor :request_validation
+    attr_accessor :request_validation, :response_validation, :coerce_params
 
-    # Test / Generation
-    attr_accessor :schema_output_dir
+    # OpenAPI meta-schema validation of generated specs and middleware-loaded
+    # documents. One of :disabled, :enabled (raise on errors), :warn_only
+    # (default, log warnings). Boolean values are accepted for backwards
+    # compatibility: `true` → :warn_only, `false` → :disabled.
+    attr_reader :strict_reference_validation
 
-    # UI (optional)
-    attr_accessor :ui_enabled
+    def strict_reference_validation=(value)
+      @strict_reference_validation = case value
+      when true, :warn_only then :warn_only
+      when false, :disabled then :disabled
+      when :enabled then :enabled
+      else
+        raise ConfigurationError,
+          "strict_reference_validation must be :disabled, :enabled, :warn_only, or a boolean"
+      end
+    end
 
-    # Coverage
-    attr_accessor :coverage_enabled
+    # UI (optional)
+    attr_accessor :ui_enabled, :ui_path, :ui_config
 
     def initialize
       @schemas = {}
       @component_paths = ["app/api_components"]
       @component_scope_paths = {}
       @camelize_keys = true
-      @key_transform = nil
       @request_validation = :disabled
       @response_validation = :disabled
-      @strict_query_params = false
       @coerce_params = true
-      @error_handler = nil
       @schema_output_dir = "swagger"
       @schema_output_format = :yaml
-      @validate_responses_in_tests = true
       @ui_enabled = false
       @ui_path = "/api-docs"
       @ui_config = {}
-      @strict_reference_validation = true
+      @strict_reference_validation = :warn_only
       @auto_validation_error_response = true
       @validation_error_schema = nil
-      @coverage_enabled = false
-      @coverage_report_path = "tmp/openapi_coverage.json"
     end
 
     def validate!

data/lib/openapi_ruby/core/document_builder.rb

@@ -60,12 +60,18 @@ module OpenapiRuby
           }
         }
 
-        # Add 400 to every operation that doesn't already define one
+        # Add 400 to operations that have parameters or a request body
         @paths.each_value do |path_item|
+          path_params = path_item["parameters"]
+
           path_item.each do |key, operation|
             next unless operation.is_a?(Hash) && operation.key?("responses")
             next if key == "parameters"
 
+            has_params = operation.key?("parameters") || path_params
+            has_body = operation.key?("requestBody")
+            next unless has_params || has_body
+
             operation["responses"]["400"] ||= {"$ref" => "#/components/responses/SchemaValidationError"}
           end
         end

data/lib/openapi_ruby/dsl/context.rb

@@ -23,8 +23,6 @@ module OpenapiRuby
       HTTP_METHODS.each do |method|
         define_method(method) do |summary = nil, &block|
           op = OperationContext.new(method, summary)
-          # Copy path-level parameters to operation
-          @path_parameters.each { |p| op.parameter(p) }
           op.instance_eval(&block) if block
           @operations[method.to_s] = op
           op
@@ -34,8 +32,8 @@ module OpenapiRuby
       def to_openapi
         result = {}
 
-        # Path-level parameters are already copied into each operation (line 27),
-        # so we don't output them at the path level to avoid duplicates.
+        result["parameters"] = @path_parameters if @path_parameters.any?
+
         @operations.each do |verb, op|
           result[verb] = op.to_openapi
         end

data/lib/openapi_ruby/engine.rb

@@ -7,6 +7,8 @@ module 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)
@@ -36,9 +38,6 @@ module OpenapiRuby
       end
     end
 
-    # Components are loaded on demand via Components::Loader (e.g. in test helpers),
-    # not at boot time — avoids cross-file dependency ordering issues.
-
     private
 
     def resolve_schema_path(config, schema_name)

data/lib/openapi_ruby/generator/schema_writer.rb

@@ -23,7 +23,7 @@ module OpenapiRuby
 
       def write!
         document = build_document
-        validate_document!(document) if OpenapiRuby.configuration.strict_reference_validation
+        validate_document!(document) unless OpenapiRuby.configuration.strict_reference_validation == :disabled
         output_path = File.join(output_dir, filename)
         FileUtils.mkdir_p(output_dir)
         File.write(output_path, format_output(document))
@@ -38,9 +38,10 @@ module OpenapiRuby
           builder.add_path(context.path_template, context.to_openapi)
         end
 
-        # Merge components from registry
+        # Merge components from registry (Loader ensures files are loaded)
         scope = @schema_config[:component_scope]
-        components = Components::Registry.instance.to_openapi_hash(scope: scope)
+        loader = Components::Loader.new(scope: scope)
+        components = loader.to_openapi_hash
         builder.merge_components(components)
 
         builder.build
@@ -62,7 +63,12 @@ module OpenapiRuby
         return if errors.empty?
 
         error_messages = errors.first(10).map { |e| e["error"] || e.to_s }
-        warn "[openapi_ruby] Generated schema '#{@schema_name}' has validation errors:\n#{error_messages.join("\n")}"
+        message = "[openapi_ruby] Generated schema '#{@schema_name}' has validation errors:\n#{error_messages.join("\n")}"
+        if OpenapiRuby.configuration.strict_reference_validation == :enabled
+          raise OpenapiRuby::ConfigurationError, message
+        else
+          warn message
+        end
       end
 
       def format_output(document)

data/lib/openapi_ruby/middleware/path_matcher.rb

@@ -21,7 +21,11 @@ module OpenapiRuby
       private
 
       def build_matchers(templates)
-        templates.map do |template|
+        # Sort templates so that static paths come before parameterized ones.
+        # This ensures `/admin_users/me` matches before `/admin_users/{id}`.
+        sorted = templates.sort_by { |t| [t.count("{"), t] }
+
+        sorted.map do |template|
           pattern = Regexp.new("\\A" + template.gsub(/\{(\w+)\}/) { "(?<#{::Regexp.last_match(1)}>[^/]+)" } + "\\z")
           [template, pattern]
         end

data/lib/openapi_ruby/middleware/request_validation.rb

@@ -139,8 +139,8 @@ module OpenapiRuby
         errors = []
         # Coerce string values for validation based on schema type
         coerced = coerce_for_validation(value, schema)
-        schemer = JSONSchemer.schema(schema)
-        schemer.validate(coerced).each do |err|
+        schema_validator = resolve_schema(schema)
+        schema_validator.validate(coerced).each do |err|
           msg = err["error"] || err["type"] || "validation failed"
           errors << "Invalid #{context}: #{msg}"
         end
@@ -170,9 +170,26 @@ module OpenapiRuby
       end
 
       def coerce_for_validation(value, schema)
-        return value unless value.is_a?(String)
+        resolved = resolve_schema_definition(schema)
+
+        if value.is_a?(Hash) && resolved.is_a?(Hash)
+          properties = resolved["properties"] || {}
+          value.each_with_object({}) do |(k, v), coerced|
+            prop_schema = properties[k] || properties[k.to_s]
+            coerced[k] = prop_schema ? coerce_for_validation(v, prop_schema) : v
+          end
+        elsif value.is_a?(String)
+          coerce_string(value, resolved)
+        else
+          value
+        end
+      rescue ArgumentError, TypeError
+        value
+      end
 
-        case schema["type"]
+      def coerce_string(value, schema)
+        type = schema.is_a?(Hash) ? schema["type"] : nil
+        case type
         when "integer"
           Integer(value)
         when "number"
@@ -190,6 +207,19 @@ module OpenapiRuby
         value
       end
 
+      def resolve_schema_definition(schema)
+        return schema unless schema.is_a?(Hash) && schema["$ref"]
+
+        ref_path = schema["$ref"].sub("#/", "").split("/")
+        ref_path.reduce(document) { |doc, key| doc&.dig(key) } || schema
+      rescue
+        schema
+      end
+
+      def document
+        @resolver.respond_to?(:document) ? @resolver.document : {}
+      end
+
       def read_request_body(request)
         return nil unless request.body
 

data/lib/openapi_ruby/middleware/schema_resolver.rb

@@ -3,7 +3,7 @@
 module OpenapiRuby
   module Middleware
     class SchemaResolver
-      def initialize(spec_path: nil, document: nil, strict_reference_validation: true)
+      def initialize(spec_path: nil, document: nil, strict_reference_validation: :warn_only)
         @spec_path = spec_path
         @document = document
         @strict_reference_validation = strict_reference_validation
@@ -41,15 +41,19 @@ module OpenapiRuby
       private
 
       def validate_document!(doc)
-        return unless @strict_reference_validation
+        return if @strict_reference_validation == :disabled
 
         schemer = JSONSchemer.openapi(doc)
         errors = schemer.validate.to_a
         return if errors.empty?
 
         error_messages = errors.first(5).map { |e| e["error"] || e.to_s }
-        raise OpenapiRuby::ConfigurationError,
-          "OpenAPI document validation failed:\n#{error_messages.join("\n")}"
+        message = "OpenAPI document validation failed:\n#{error_messages.join("\n")}"
+        if @strict_reference_validation == :enabled
+          raise OpenapiRuby::ConfigurationError, message
+        else
+          warn message
+        end
       end
 
       def load_document

data/lib/openapi_ruby/version.rb

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

data/lib/tasks/openapi_ruby.rake

@@ -8,7 +8,7 @@ namespace :openapi_ruby do
 
     # Spawn a subprocess so RAILS_ENV defaults to "test" cleanly,
     # just like rswag did with RSpec::Core::RakeTask.
-    env = {"RAILS_ENV" => ENV.fetch("RAILS_ENV", "test")}
+    env = {"RAILS_ENV" => ENV.fetch("RAILS_ENV", "test"), "OPENAPI_RUBY_GENERATING" => "true"}
     script = generate_script(framework, pattern)
     command = "bundle exec ruby -e #{Shellwords.escape(script)}"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-ruby
 version: !ruby/object:Gem::Version
-  version: 3.0.3
+  version: 3.1.1
 platform: ruby
 authors:
 - Morten Hartvig