openapi-ruby 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 953f7f56ecdec3d8ee0f1f1261e49328e53d0aab5041b43f47a6e1138a2e880f
-  data.tar.gz: bec8a51340348604307f17791824d9327e7ceee7b58a8f35533ef7036c12156f
+  metadata.gz: 2e97365e4c2b566d59db1f4946a2b0e1f45f8ee9b938f2b5c049ac0ac9f56dcc
+  data.tar.gz: 431709a674d6a028fd8a14f47200761215a6e4576888009b3b2b637fd5a453b9
 SHA512:
-  metadata.gz: c62b49da036fe1dbb27b3f7ce2937a044427ea89ded288bdab1c33dab6fc041e31c89ecb75fd2e2419731cd0f803428baed9ed5152cdf01d7cd77b42b004642e
-  data.tar.gz: 5e2bbbcf02c286120207fc06a9f86c66b2618c9766a78b4b94c215641d0c2a5173aa4c45705e4fd2e6ed909271c63000a65182d159f22f3d716a4742dcbc6bae
+  metadata.gz: 0a670b21d1043c474b2eead1844c47258521df05b247d561a5578de4c8495a6519b575c7b3d2d4fe4fc54c22d5d524e45ee2fab492e99e3366c8eab5bc381ecf
+  data.tar.gz: e2981bfa965fef6c6db6767d8e36592b8166fa20f675265c9d0147265565250e845093ca4fb3dc3bd3a7d2a2b1c3a7c6cb9d52169a0142bc0be2a90727a50b77

data/README.md

@@ -68,6 +68,10 @@ OpenapiRuby.configure do |config|
   config.request_validation = :disabled   # :enabled, :disabled, :warn_only
   config.response_validation = :disabled
 
+  # Test DSL: validate requests against declared operations before sending.
+  # Enabled by default; set to false to disable.
+  config.test_request_validation = true
+
   # Optional Swagger UI (disabled by default)
   config.ui_enabled = false
 end
@@ -230,6 +234,12 @@ rails generate openapi_ruby:component BearerAuth security_schemes
 require "openapi_ruby/rspec"
 ```
 
+RSpec supports two DSL styles. Both generate the same OpenAPI spec and validate responses (and requests) against it.
+
+### Style 1: `path` / `run_test!`
+
+Schema definition and test execution are interleaved. Each `response` block uses `let` values and `run_test!` to send the request inline:
+
 ```ruby
 # spec/requests/users_spec.rb
 require "openapi_helper"
@@ -293,11 +303,71 @@ RSpec.describe "Users API", type: :openapi do
 end
 ```
 
+### Style 2: `api_path` / `assert_api_response`
+
+Schema definition at the top, normal RSpec examples underneath. Mirrors the Minitest DSL and is useful when you want basic schema validation separated from detailed edge-case tests:
+
+```ruby
+require "openapi_helper"
+
+RSpec.describe "Users API", type: :openapi do
+  openapi_schema :public_api
+
+  api_path "/api/v1/users" do
+    get "List users" do
+      tags "Users"
+      produces "application/json"
+
+      response 200, "returns all users" do
+        schema type: :array, items: { "$ref" => "#/components/schemas/User" }
+      end
+    end
+
+    post "Create a user" do
+      consumes "application/json"
+
+      request_body required: true, content: {
+        "application/json" => {
+          schema: { "$ref" => "#/components/schemas/UserInput" }
+        }
+      }
+
+      response 201, "user created" do
+        schema "$ref" => "#/components/schemas/User"
+      end
+
+      response 422, "validation errors" do
+        schema "$ref" => "#/components/schemas/ValidationErrors"
+      end
+    end
+  end
+
+  # Normal RSpec examples
+  it "returns all users" do
+    User.create!(name: "Jane", email: "jane@example.com")
+
+    assert_api_response :get, 200 do
+      expect(parsed_body.length).to eq(1)
+    end
+  end
+
+  it "creates a user" do
+    assert_api_response :post, 201, body: { name: "Jane", email: "jane@example.com" } do
+      expect(parsed_body["name"]).to eq("Jane")
+    end
+  end
+end
+```
+
+`assert_api_response` accepts `params:`, `headers:`, `body:`, and `path_params:` keyword arguments. It validates the response status and body schema automatically, then yields to the block for additional expectations.
+
 ### DSL Reference
 
 | Method | Level | Description |
 |--------|-------|-------------|
-| `path(template, &block)` | Top | Define an API path |
+| `path(template, &block)` | Top | Define an API path (style 1) |
+| `api_path(template, &block)` | Top | Define an API path (style 2) |
+| `openapi_schema(name)` | Top | Set the schema name (style 2) |
 | `get/post/put/patch/delete(summary, &block)` | Path | Define an operation |
 | `tags(*tags)` | Operation | Tag the operation |
 | `operationId(id)` | Operation | Set operation ID |
@@ -311,7 +381,9 @@ end
 | `response(status, description, &block)` | Operation | Define expected response |
 | `schema(definition)` | Response | Response body schema |
 | `header(name, schema:, **opts)` | Response | Response header |
-| `run_test!(&block)` | Response | Execute request and validate |
+| `run_test!(&block)` | Response | Execute request and validate (style 1) |
+| `assert_api_response(method, status, **opts, &block)` | Example | Execute request and validate (style 2) |
+| `parsed_body` | Example | Parsed JSON response body |
 
 ## Testing with Minitest
 

data/lib/openapi_ruby/adapters/minitest.rb

@@ -81,6 +81,21 @@ module OpenapiRuby
             request_args = {params: query_params, headers: headers}
           end
 
+          # Validate the request against the declared operation (skip for error responses,
+          # since those tests intentionally send invalid data)
+          if OpenapiRuby.configuration.test_request_validation && expected_status < 400
+            document_hash = build_validation_document(context.schema_name)
+            req_errors = Testing::RequestValidator.new(document_hash).validate(
+              operation: operation,
+              path_context: context,
+              params: params,
+              headers: headers,
+              body: body,
+              path_params: path_params
+            )
+            assert req_errors.empty?, "Request validation failed:\n#{req_errors.join("\n")}"
+          end
+
           send(method, path, **request_args)
 
           # Validate response
@@ -181,6 +196,23 @@ module OpenapiRuby
           end.uniq { |p| [p[:name], p[:in]] }
         end
 
+        def build_validation_document(schema_name)
+          return nil unless schema_name
+
+          config = OpenapiRuby.configuration
+          schema_config = config.schemas[schema_name.to_sym] || 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 |ctx|
+            builder.add_path(ctx.path_template, ctx.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
+
         def parse_response_body
           return nil if response.body.empty?
 

data/lib/openapi_ruby/adapters/rspec.rb

@@ -11,6 +11,22 @@ module OpenapiRuby
       # All methods are inherited by nested describe/context/it_behaves_like blocks.
       # Data is stored in RSpec metadata which propagates to child groups.
       module ExampleGroupHelpers
+        def openapi_schema(name)
+          metadata[:openapi_schema_name] = name.to_sym
+        end
+
+        # Minitest-style DSL: define the schema at the top of the spec file,
+        # then write normal RSpec examples underneath using assert_api_response.
+        def api_path(template, &block)
+          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
+          DSL::MetadataStore.register(context)
+          context
+        end
+
         def path(template, &block)
           schema_name = metadata[:openapi_schema_name]
           context = DSL::Context.new(template, schema_name: schema_name)
@@ -104,6 +120,100 @@ module OpenapiRuby
 
       # Instance-level helper methods mixed into RSpec examples
       module ExampleHelpers
+        # 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)
+          meta = ::RSpec.current_example.metadata
+          context = find_api_context_for(meta, method, path_params)
+          raise OpenapiRuby::Error, "No api_path defined for #{method.upcase} in this example group" unless context
+
+          operation = context.operations[method.to_s]
+          raise OpenapiRuby::Error, "No #{method.upcase} operation defined" unless operation
+
+          response_ctx = operation.responses[expected_status.to_s]
+          raise OpenapiRuby::Error, "No response #{expected_status} defined for #{method.upcase}" unless response_ctx
+
+          base_path = resolve_base_path(context.schema_name)
+          path = "#{base_path}#{expand_path(context.path_template, params.merge(path_params))}"
+
+          # Resolve security scheme parameters
+          resolve_security_params(operation, meta).each do |param|
+            val = params[param[:name].to_sym] || params[param[:name]]
+            next if val.nil?
+
+            case param[:in].to_s
+            when "header" then headers[param[:name]] = val
+            when "query" then params[param[:name]] = val
+            when "cookie" then headers["Cookie"] = "#{param[:name]}=#{val}"
+            end
+          end
+
+          headers["Accept"] ||= "application/json"
+
+          path_param_names = context.path_parameters.map { |p| p["name"] }
+          query_params = params.reject { |k, _| path_param_names.include?(k.to_s) }
+
+          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")
+              {params: body, headers: headers}
+            else
+              {
+                params: body.is_a?(String) ? body : body.to_json,
+                headers: headers.merge("Content-Type" => content_type)
+              }
+            end
+          else
+            request_args = {headers: headers}
+          end
+
+          if query_params.any?
+            path = "#{path}?#{Rack::Utils.build_nested_query(query_params)}"
+          end
+
+          # Validate the request against the declared operation (skip for error responses,
+          # since those tests intentionally send invalid data)
+          if OpenapiRuby.configuration.test_request_validation && expected_status < 400
+            document_hash = OpenapiRuby::Adapters::RSpec.validation_document_for(context.schema_name)
+            req_errors = Testing::RequestValidator.new(document_hash).validate(
+              operation: operation,
+              path_context: context,
+              params: params,
+              headers: headers,
+              body: body,
+              path_params: path_params
+            )
+            raise "Request validation failed:\n#{req_errors.join("\n")}" unless req_errors.empty?
+          end
+
+          send(method, path, **request_args)
+
+          unless response.status == expected_status
+            raise "Expected status #{expected_status}, got #{response.status}\nResponse body: #{response.body}"
+          end
+
+          if response_ctx.schema_definition
+            validator = Testing::ResponseValidator.new(
+              OpenapiRuby::Adapters::RSpec.validation_document_for(context.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
+
+          instance_eval(&block) if block
+        end
+
+        def parsed_body
+          parsed_response_body
+        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)
@@ -164,6 +274,35 @@ module OpenapiRuby
             request_args = {headers: headers}
           end
 
+          # Validate the request against the declared operation (skip for error responses,
+          # since those tests intentionally send invalid data)
+          response_ctx = find_in_metadata(metadata, :openapi_response)
+          expected_status = response_ctx&.status_code.to_i
+          if OpenapiRuby.configuration.test_request_validation && operation && expected_status < 400
+            path_ctx = find_in_metadata(metadata, :openapi_path_context)
+            schema_name = find_in_metadata(metadata, :openapi_schema_name)
+
+            # Collect resolved path param values for validation
+            path_param_values = {}
+            (path_ctx&.path_parameters || []).each do |param|
+              name = param["name"]
+              next unless name
+              val = resolve_let(name.to_sym)
+              path_param_values[name] = val if val
+            end
+
+            document_hash = OpenapiRuby::Adapters::RSpec.validation_document_for(schema_name)
+            req_errors = Testing::RequestValidator.new(document_hash).validate(
+              operation: operation,
+              path_context: path_ctx,
+              params: params,
+              headers: headers,
+              body: body,
+              path_params: path_param_values
+            )
+            raise "Request validation failed:\n#{req_errors.join("\n")}" unless req_errors.empty?
+          end
+
           send(method.to_sym, path, **request_args)
         end
 
@@ -195,6 +334,29 @@ module OpenapiRuby
 
         private
 
+        def find_api_context_for(metadata, method, path_params)
+          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
+        end
+
+        def expand_path(template, params)
+          template.gsub(/\{(\w+)\}/) do
+            name = ::Regexp.last_match(1)
+            value = params[name.to_sym] || params[name.to_s]
+            value || "{#{name}}"
+          end
+        end
+
         def resolve_path(metadata)
           path_ctx = find_in_metadata(metadata, :openapi_path_context)
           template = path_ctx&.path_template || ""

data/lib/openapi_ruby/configuration.rb

@@ -18,6 +18,10 @@ module OpenapiRuby
     # Middleware (runtime validation)
     attr_accessor :request_validation, :response_validation, :coerce_params
 
+    # Test DSL: validate that requests match the declared operation before sending.
+    # Enabled by default; set to false to disable.
+    attr_accessor :test_request_validation
+
     # 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
@@ -46,6 +50,7 @@ module OpenapiRuby
       @request_validation = :disabled
       @response_validation = :disabled
       @coerce_params = true
+      @test_request_validation = true
       @schema_output_dir = "swagger"
       @schema_output_format = :yaml
       @ui_enabled = false

data/lib/openapi_ruby/testing/request_validator.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Testing
+    class RequestValidator
+      def initialize(document_hash = nil)
+        @document_hash = document_hash
+      end
+
+      def validate(operation:, path_context: nil, params: {}, headers: {}, body: nil, path_params: {})
+        errors = []
+
+        # Collect all parameters (path-level + operation-level)
+        all_parameters = (path_context&.path_parameters || []) + (operation.parameters || [])
+
+        # Validate each declared parameter
+        all_parameters.each do |param|
+          name = param["name"]
+          next unless name
+
+          value = extract_param_value(param, params, headers, path_params)
+
+          if value.nil?
+            errors << "Missing required #{param["in"]} parameter: #{name}" if param["required"]
+            next
+          end
+
+          if param["schema"]
+            param_errors = validate_value(value, param["schema"], "#{param["in"]} parameter '#{name}'")
+            errors.concat(param_errors)
+          end
+        end
+
+        # Validate request body
+        errors.concat(validate_request_body(operation, body))
+
+        errors
+      end
+
+      private
+
+      def extract_param_value(param, params, headers, path_params)
+        name = param["name"]
+
+        case param["in"]
+        when "query"
+          params[name.to_sym] || params[name.to_s]
+        when "path"
+          path_params[name.to_sym] || path_params[name.to_s]
+        when "header"
+          headers[name] || headers[name.downcase]
+        end
+      end
+
+      def validate_request_body(operation, body)
+        errors = []
+        rb_spec = operation.request_body_definition
+        return errors unless rb_spec
+
+        if rb_spec["required"] && body.nil?
+          errors << "Request body is required"
+          return errors
+        end
+
+        return errors unless body && rb_spec["content"]
+
+        media_type = rb_spec["content"].keys.first
+        schema = rb_spec.dig("content", media_type, "schema")
+        return errors unless schema
+
+        validate_against_schema(body, schema, "request body", errors)
+        errors
+      end
+
+      def validate_value(value, schema, context)
+        coerced = coerce_for_validation(value, schema)
+        schema_validator = resolve_schema(schema)
+        return [] unless schema_validator
+
+        schema_validator.validate(coerced).map do |err|
+          "Invalid #{context}: #{format_error(err)}"
+        end
+      rescue => e
+        ["Invalid #{context}: #{e.message}"]
+      end
+
+      def validate_against_schema(data, schema, context, errors)
+        schema_validator = resolve_schema(schema)
+        return unless schema_validator
+
+        schema_validator.validate(data).each do |err|
+          pointer = err["data_pointer"] || ""
+          msg = format_error(err)
+          location = pointer.empty? ? context : "#{context} at #{pointer}"
+          errors << "Invalid #{location}: #{msg}"
+        end
+      rescue => e
+        errors << "Invalid #{context}: #{e.message}"
+      end
+
+      def resolve_schema(schema)
+        if schema.is_a?(Hash) && schema["$ref"] && @document_hash
+          JSONSchemer.openapi(@document_hash).ref(schema["$ref"])
+        elsif contains_ref?(schema)
+          nil # Cannot validate $ref without document
+        else
+          JSONSchemer.schema(schema)
+        end
+      rescue
+        nil
+      end
+
+      def coerce_for_validation(value, schema)
+        return value unless value.is_a?(String)
+
+        type = schema.is_a?(Hash) ? schema["type"] : nil
+        case type
+        when "integer" then Integer(value)
+        when "number" then Float(value)
+        when "boolean"
+          case value.downcase
+          when "true", "1" then true
+          when "false", "0" then false
+          else value
+          end
+        else value
+        end
+      rescue ArgumentError, TypeError
+        value
+      end
+
+      def contains_ref?(value)
+        case value
+        when Hash
+          return true if value.key?("$ref")
+          value.values.any? { |v| contains_ref?(v) }
+        when Array
+          value.any? { |v| contains_ref?(v) }
+        else
+          false
+        end
+      end
+
+      def format_error(error)
+        if error.is_a?(Hash)
+          error["error"] || error["type"] || "validation failed"
+        else
+          error.to_s
+        end
+      end
+    end
+  end
+end

data/lib/openapi_ruby/version.rb

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

data/lib/openapi_ruby.rb

@@ -43,6 +43,7 @@ require_relative "openapi_ruby/dsl/context"
 require_relative "openapi_ruby/dsl/metadata_store"
 require_relative "openapi_ruby/testing/request_builder"
 require_relative "openapi_ruby/testing/response_validator"
+require_relative "openapi_ruby/testing/request_validator"
 require_relative "openapi_ruby/testing/assertions"
 require_relative "openapi_ruby/testing/coverage"
 require_relative "openapi_ruby/generator/schema_writer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-ruby
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.2.0
 platform: ruby
 authors:
 - Morten Hartvig
@@ -117,6 +117,7 @@ files:
 - lib/openapi_ruby/testing/assertions.rb
 - lib/openapi_ruby/testing/coverage.rb
 - lib/openapi_ruby/testing/request_builder.rb
+- lib/openapi_ruby/testing/request_validator.rb
 - lib/openapi_ruby/testing/response_validator.rb
 - lib/openapi_ruby/version.rb
 - lib/tasks/openapi_ruby.rake