openapi_first 3.4.3 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa35ee9098e786a73c8d0de102d691cb0f5cec972e60e9a8d96d439f63eef872
-  data.tar.gz: b6f8461c433753a49563055b4fd3156cbbacf0c89d5f7e2f2a7f1366c2c3b32c
+  metadata.gz: 47dffdd527985dd188f08ea57ff1104f3e51203746175cf4a964c757af8ebd6e
+  data.tar.gz: c67d1e706d644caadd9397bfdb2eef046317e2c4ac86bfd8e261b60ad7136bf7
 SHA512:
-  metadata.gz: 2146d351211ebc10237dd8f6d30381d15d99ac15bf0cfa05a9095b6f493738b48c4e406b0d359fcc6f11c9910702b0e3ad4003b6513d32cd2390c81a356fd21b
-  data.tar.gz: 2235965c286c2d182a77b491422c18a25010f69c0e91e87e50731334aa5515fdbe3cd06d03a4a509c3f07b07f1405a928b50a6b037ed022fc0dd3b60e8bf1be9
+  metadata.gz: e5e16ce4c6c4756517e9bff345eb7182937b239be36a038444680f61b169790aef3c5d10c3c1d8b2be0e3332b72784a3722ba3ea99de0e7712f4c1e48284c0ec
+  data.tar.gz: fa631d3327bbcf640645d2b762d00ac8baa4bf5c87276c9c00cc280e58d1985a419a64ccd4b8521f411f9d5f47442ae9efc31f0bf959b5a8d4f24fb8205de7a7

data/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 ## Unreleased
 
+## 4.0.0
+
+This release has no stricter or less strict request validation. It changes mostly internal stuff and adds a Sinatra integration. It's a major version, but it should be safe to upgrade.
+
+#### Breaking changes
+- Uploaded files are no longer read during request validation. Before, the whole content of every `multipart/form-data` part that was sent as a file was read into memory, which allowed a single large upload to any documented multipart route to exhaust the memory of the server process. Such a field is now passed through as Rack parsed it (`{ filename:, type:, name:, tempfile:, head: }`), which is the same shape that Sinatra and Hanami hand to your application. Use `parsed_body['file'][:tempfile]` to read or stream the file.
+  - The content of these fields is not validated anymore, so `minLength`, `maxLength` or `pattern` on a field that was sent as a file are ignored.
+  - An `after_request_body_property_validation` hook sees an empty String instead of the file.
+  - Fields that were not sent as a file, and fields with a JSON `contentType` in the `encoding` map, are read and validated as before.
+- The `openapi_parameters` gem was merged into openapi_first and is not a dependency anymore. Parameter parsing now lives in openapi_first itself. If you registered a parser for parameters that use a `content` field, use `OpenapiFirst::ParameterContentParsers.register` instead of `OpenapiParameters::ContentParsers.register`.
+- Changed: `OpenapiFirst::ResponseHeader` (returned by `Response#headers`, renamed from `OpenapiFirst::Header`) exposes `parameter`, an `OpenapiFirst::Parameter`, instead of `node`.
+- Changed: `OpenapiFirst::Request#parameters` returns the parameters that are defined for a request as `OpenapiFirst::Parameter` objects, which expose `name`, `location`, `schema`, `required?`, `deprecated?`, `style`, `explode?` and `media_type`.
+
+#### Removed deprecations
+- Removed: `OpenapiFirst::Configuration#request_validation_raise_error` and `#response_validation_raise_error` (both reader and writer), deprecated since 3.0.0. Pass `raise_error:` to middlewares instead.
+- Removed: `OpenapiFirst::Test::Configuration#coverage_formatter`, `#coverage_formatter=`, `#coverage_formatter_options` and `#coverage_formatter_options=`, deprecated since 3.4.0. Use `#coverage_reporter` / `#coverage_reporter_options` instead.
+- Removed: `OpenapiFirst::Test::Coverage::TerminalFormatter`, deprecated since 3.4.0. Use `OpenapiFirst::Test::Coverage::TerminalReporter` instead.
+- Removed: The `formatter:` keyword of `OpenapiFirst::Test.report_coverage`, deprecated since 3.4.0. Use `reporter:` instead.
+- Removed: `OpenapiFirst::Test::Coverage::TerminalReporter#format`, deprecated since 3.4.0. Use `#report` instead.
+
+#### Added
+- Added: API coverage now reports skipped requests and responses.
+- Added: OpenAPI 3.2 documents are accepted, but not fully supported yet. They are handled using the OpenAPI 3.1 rules, so features introduced in 3.2 may be ignored. Loading such a document prints a warning. Operations defined under `additionalOperations` are routed. See [#469](https://github.com/ahx/openapi_first/issues/469).
+- Added: Show all covered endpoints in HTML coverage reporter and filter covered/uncovered endpoints.
+- Added: Sinatra integration (OpenapiFirst::Sinatra)
+  A Sinatra extension to define routes by referencing OpenAPI operations:
+
+  ```ruby
+    require 'openapi_first/sinatra'
+
+    class PetsApi < Sinatra::Base
+      register OpenapiFirst::Sinatra
+      openapi 'openapi.yaml'
+
+      operation :index_pets do |params|
+        json index_pets(params[:filter])
+      end
+
+      operation :create_pet do
+        pet = create_pet(parsed_body)
+        headers['Location'] = operation_url(:show_pet, petId: pet.id)
+        status :created
+        json pet
+      end
+
+      operation :show_pet do |params|
+        json show_pet(params[:petId])
+      end
+    end
+  ```
+
+  The HTTP method and path for each route come from the operationId.
+  Request validation is called automatically for these operations.
+
+#### Fixed
+- Fixed: Validating against a schema from a referenced file raised `ArgumentError` in OpenAPI 3.0 documents when a top-level key of that file collides with a JSON Schema keyword, such as `$ref: 'parameters.yaml#/id'`. The containing file is no longer parsed as a schema itself, so such keys work like any other now. See [#348](https://github.com/ahx/openapi_first/issues/348).
+- Fixed: `$ref`s nested inside the schema of a parameter or a response header are resolved now, so these values are unpacked and converted as described. Before, only a `$ref` at the top level of the schema was resolved. See #450.
+- Fixed: The JSON schema of a parameter that uses a `content` field with a `$ref`'d schema is resolved now.
+- Fixed: Loading a document no longer raises `NoMethodError` when a parameter has neither `schema` nor `content`.
+- Fixed: Repeated values for a query parameter that describes an object or uses `content` (`?filter=a&filter=b`) raised a `NoMethodError` or `TypeError`. The values are validated against the schema now, which returns an `:invalid_query` failure.
+- Fixed: A parameter with `style: matrix` raised a `NoMethodError` if its value did not contain the parameter name, or contained it more than once. Such values are parsed like their `explode` counterpart now.
+- Fixed: A parameter with `style: matrix`, or a path parameter that describes an object, raised an `ArgumentError` if its value had an invalid `%`-encoding. Such values are validated against the schema now.
+- Fixed: A path, header or cookie parameter that uses a `content` field with a value that could not be parsed as that media type (e.g. `007` as `application/json`) was converted using the parameter's schema type anyway, which could make an invalid value pass schema validation (e.g. as the integer `7`). Such values are left as they are now, so schema validation rejects them as before.
+- Fixed: Reduced memory retained by a loaded `Definition`. Response headers with a schema no longer keep the whole raw document node alive, and a couple of build-time-only hashes were replaced with more compact structures.
+
+
 ## 3.4.3
 
 Fixed: Loading a document no longer raises `NoMethodError: undefined method 'schema' for nil` when a Media Type Object has no `schema` (e.g. it only declares an `example`). `schema` is optional in a Media Type Object; such media types now impose no body-schema constraint.

data/README.md

@@ -49,7 +49,7 @@ end
 
 ## Configuration
 
-You should register OADs globally so you don't have to load the file multiple times or to refernce them by Symbol (like :v1 in this example).
+You should register OADs globally so you don't have to load the file multiple times.
 ```ruby
 OpenapiFirst.configure do |config|
   config.register('openapi/openapi.yaml') # :default
@@ -57,7 +57,7 @@ OpenapiFirst.configure do |config|
 end
 ```
 
-You can configure default options globally:
+You can configure defaults globally:
 
 ```ruby
 OpenapiFirst.configure do |config|
@@ -119,7 +119,7 @@ content-type: "application/problem+json"
 openapi_first offers a [JSON:API](https://jsonapi.org/) error response by passing `error_response: :jsonapi`:
 
 ```ruby
-use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml', error_response: :jsonapi
+use OpenapiFirst::Middlewares::RequestValidation, error_response: :jsonapi
 ```
 
 <details>
@@ -166,9 +166,28 @@ use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml', error_response
 You can build your own custom error response with `error_response: MyCustomClass` that implements `OpenapiFirst::ErrorResponse`.
 You can define custom error responses globally by including / implementing `OpenapiFirst::ErrorResponse` and register it via `OpenapiFirst.register_error_response(my_name, MyCustomErrorResponse)` and set `error_response: my_name`.
 
+#### Multipart file uploads
+
+Uploaded files are not read during request validation. A `multipart/form-data` field that was sent as a file is passed through as Rack parsed it – the same shape that Sinatra and Hanami hand to your application:
+
+```ruby
+file = validated_request.parsed_body['file']
+file[:filename] # => "cat.jpg"
+file[:type]     # => "image/jpeg"
+file[:tempfile] # => #<Tempfile …> Read or stream this in your application.
+```
+
+The tempfile is only usable while the request is being handled, because Rack removes it afterwards.
+
+This means the _content_ of these fields is not validated, so `minLength`, `maxLength` or `pattern` on a field that was sent as a file are ignored. Fields that were not sent as a file are read and validated as usual, and a field with `contentType: application/json` in the `encoding` map is still parsed as JSON.
+
 ### Response validation
 
+> [!WARNING]
+> You should use [Contract Testing](#contract-testing) instead of this middleware.
+
 This middleware raises an error by default if the response is not valid.
+
 This can be useful in a test or staging environment, especially if you are adopting OpenAPI for an existing implementation.
 
 ```ruby
@@ -178,7 +197,7 @@ use OpenapiFirst::Middlewares::ResponseValidation if ENV['RACK_ENV'] == 'test'
 use OpenapiFirst::Middlewares::ResponseValidation, raise_error: false
 ```
 
-If you are adopting OpenAPI you can use these options together with [hooks](#hooks) to get notified about requests/responses that do match your API description.
+If you are adopting OpenAPI you can use these options together with [hooks](#hooks) to get notified about requests/responses that do not match your API description.
 
 ## Contract Testing
 
@@ -192,36 +211,17 @@ Here is how to set it up:
     require 'openapi_first'
     OpenapiFirst::Test.setup
     ```
-2. Observe your application. You can do this in multiple ways:
-    - Add an `app` method to your tests (which is called by rack-test) that wraps your application with silent request / response validation.
-      ```ruby
-      module RequestSpecHelpers
-        def app
-          OpenapiFirst::Test.app(MyApp)
-        end
-      end
-
-      RSpec.configure do |config|
-        config.include RequestSpecHelpers, type: :request
-      end
-      ```
-
-      Or do this by creating a Module and including it to add an "app" method.
-
-      ```ruby
-      RSpec.configure do |config|
-        config.include OpenapiFirst::Test::Methods[MyApp], type: :request
-      end
-      ```
-3. Run your tests. The Coverage feature will tell you about missing or invalid requests/responses:
-      ```
-      ✓ GET /stations
-        ✓ 200(application/json)
-        ❌ 200(application/xml) – No responses tracked!
-        ❌ 400(application/problem+json) – No responses tracked!
-      ```
-
-      Now add tests for all those "❌" to make them "✓" and you're green!
+2. Observe your application.
+    If you are using plain rack-test (sinatra, roda, hanami, etc.), this will add an `app` method that wraps your application with silent request / response validation:
+
+    ```ruby
+    RSpec.configure do |config|
+      config.include OpenapiFirst::Test::Methods[MyApp], type: :request
+    end
+    ```
+
+    There are other ways to monitor your app, see `OpenapiFirst::Test.observe` (rails) or `OpenapiFirst::Test.app`.
+3. Run your tests. The Coverage feature will produce a HTML report at `coverage/openapi_coverage.html` with missing or invalid requests/responses.
 
 > [!NOTE]
 > Check out [faraday-openapi](https://codeberg.org/ahx/faraday-openapi) to have your API _client_ validate request/responses against an OAD, which is useful to validate HTTP mocks during testing.
@@ -239,12 +239,11 @@ OpenapiFirst::Test.setup do |test|
   
   test.ignore_response_error do |validated_response, rack_request|
     # Ignore invalid response bodies on certain paths
-    validated_request.path.start_with?('/api/legacy/stuff') && validated_request.error.type ==  :invalid_body      
+    rack_request.path.start_with?('/api/legacy/stuff') && validated_response.error.type ==  :invalid_body      
   end
 end
 ```
 
-
 OpenapiFirst::Test raises an error when a response status is not defined except for 404 and 500. You can change this:
 
 ```ruby
@@ -276,7 +275,7 @@ Skip coverage for a request and all responses alltogether of a route with `skip_
 ```ruby
 OpenapiFirst::Test.setup do |test|
   test.skip_coverage do |path, request_method|
-    path == '/bookings/{bookingId}' && requests_method == 'DELETE'
+    path == '/bookings/{bookingId}' && request_method == 'DELETE'
   end
 end
 ```
@@ -351,6 +350,18 @@ validated_request.operation['operationId'] => "getStuff"
 validated_request.request_definition.path # => "/pets/{petId}"
 validated_request.request_definition.operation_id # => "showPetById"
 
+# Inspect the parameters that are defined for this request, in the order path, query, header, cookie.
+# Parameters that openapi_first ignores (Content-Type, Accept, Authorization) are not included.
+parameter = validated_request.request_definition.parameters.first
+parameter.name # => "petId"
+parameter.location # => "path" ("path", "query", "header" or "cookie")
+parameter.schema # => { "type" => "integer" } (the JSON Schema, with $refs resolved)
+parameter.required? # => true
+parameter.deprecated? # => false
+parameter.style # => "simple"
+parameter.explode? # => false
+parameter.media_type # => "application/json" if the parameter uses `content`, otherwise nil
+
 # Or you can raise an exception if validation fails:
 definition.validate_request(rack_request, raise_error: true) # Raises OpenapiFirst::RequestInvalidError or OpenapiFirst::NotFoundError if request is invalid
 ```
@@ -360,7 +371,7 @@ definition.validate_request(rack_request, raise_error: true) # Raises OpenapiFir
 ```ruby
 validated_response = definition.validate_response(rack_request, rack_response)
 
-# Inspect the response and access parsed parameters and
+# Inspect the response and access parsed parameters
 validated_response.valid?
 validated_response.invalid?
 validated_response.error # => Failure object or nil
@@ -369,7 +380,7 @@ validated_response.parsed_body
 validated_response.parsed_headers
 
 # Or you can raise an exception if validation fails:
-definition.validate_response(rack_request,rack_response, raise_error: true) # Raises OpenapiFirst::ResponseInvalidError or OpenapiFirst::ResponseNotFoundError
+definition.validate_response(rack_request, rack_response, raise_error: true) # Raises OpenapiFirst::ResponseInvalidError or OpenapiFirst::ResponseNotFoundError
 ```
 
 ## Hooks
@@ -416,12 +427,54 @@ Using rack middlewares is supported in probably all Ruby web frameworks.
 
 The contract testing feature is designed to be used via rack-test, which should be compatible all Ruby web frameworks as well.
 
-That aside, closer integration with specific frameworks like Sinatra, Hanami, Roda or others would be great. If you have ideas, pain points or PRs, please don't hesitate to [share](https://github.com/ahx/openapi_first/discussions).
+That aside, closer integration with specific frameworks like Hanami, Roda or others would be great. If you have ideas, pain points or PRs, please don't hesitate to [share](https://github.com/ahx/openapi_first/discussions).
+
+### Sinatra
+
+`OpenapiFirst::Sinatra` is a Sinatra extension to define routes by referencing operations in your OpenAPI description. The URL and HTTP method for each route are read from the OAD by `operationId`, so they are never repeated in your code – the API description stays the single source of truth for your routes.
+
+```ruby
+require 'sinatra/base'
+require 'openapi_first/sinatra'
+
+class PetsApi < Sinatra::Base
+  register OpenapiFirst::Sinatra
+  openapi 'openapi.yaml'
+
+  operation :index_pets do |params|
+    json index_pets(params[:filter])
+  end
+
+  operation :create_pet do
+    json create_pet(parsed_body[:data])
+  end
+end
+```
+
+In a **classic** (top-level) app the extension registers itself, so requiring the file is enough:
+
+```ruby
+require 'sinatra'
+require 'openapi_first/sinatra'
+
+openapi 'openapi.yaml'
+
+operation :create_pet do
+  json create_pet(parsed_body)
+end
+```
+
+Each `operation` route validates its request against the description before the block runs, so contract violations return `400`/`415` and the block is not reached. Validation reuses Sinatra's own routing (the operation's path and method are known when the route is defined), so openapi_first does not run its own router – there is no request-validation middleware.
+
+Because routing is left to Sinatra, requests to paths without an `operation` block fall through to Sinatra's normal handling (a `404` by default), and you can add plain Sinatra routes (health checks, assets, …) alongside `operation` blocks. Likewise, an undocumented method on a documented path returns Sinatra's `404`.
+
+Use a String for operationIds that are not valid Ruby symbols, e.g. `operation 'pets.list'`.
+
+See [`sinatra.rb`](lib/openapi_first/sinatra.rb) for a more details.
 
 ## Alternatives
 
 This gem was inspired by [committee](https://github.com/interagent/committee) (Ruby) and [Connexion](https://github.com/spec-first/connexion) (Python).
-Here is a [feature comparison between openapi_first and committee](https://gist.github.com/ahx/1538c31f0652f459861713b5259e366a).
 
 ## Frequently Asked Questions
 
@@ -441,7 +494,7 @@ Here your OpenAPI schema defines endpoints starting with `/resource` but your ac
 
 ```ruby
 oad = OpenapiFirst.load('openapi.yaml') do |config|
-  config.path = ->(req) { request.path.delete_prefix('/api') }
+  config.path = ->(req) { req.path.delete_prefix('/api') }
 end
 use OpenapiFirst::Middlewares::RequestValidation, oad
 ```

data/lib/openapi_first/builder.rb

@@ -4,7 +4,10 @@ require 'json_schemer'
 
 require_relative 'failure'
 require_relative 'router'
-require_relative 'header'
+require_relative 'response_header'
+require_relative 'parameter'
+require_relative 'parameters_parser'
+require_relative 'query_string_parser'
 require_relative 'request'
 require_relative 'response'
 require_relative 'schema/hash'
@@ -52,7 +55,11 @@ module OpenapiFirst
       version = document['openapi']
       case version
       when /\A3\.1\.\d+\z/
-        document.fetch('jsonSchemaDialect') { JSONSchemer::OpenAPI31::BASE_URI.to_s }
+        openapi31_meta_schema(document)
+      when /\A3\.2\.\d+\z/
+        warn "OpenAPI 3.2 is not fully supported. #{filepath || 'This API description'} is handled " \
+             'using the OpenAPI 3.1 rules, so features introduced in 3.2 may be ignored.'
+        openapi31_meta_schema(document)
       when /\A3\.0\.\d+\z/
         JSONSchemer::OpenAPI30::BASE_URI.to_s
       else
@@ -60,60 +67,86 @@ module OpenapiFirst
       end
     end
 
-    def router # rubocop:disable Metrics/MethodLength
+    def openapi31_meta_schema(document)
+      document.fetch('jsonSchemaDialect') { JSONSchemer::OpenAPI31::BASE_URI.to_s }
+    end
+
+    def router
       router = OpenapiFirst::Router.new
       @contents.fetch('paths').each do |path, path_item_object|
         path_parameters = path_item_object['parameters'] || []
         path_item_object.resolved.keys.intersection(REQUEST_METHODS).map do |request_method|
           operation_object = path_item_object[request_method]
-          operation_parameters = operation_object['parameters'] || []
-          parameters = parse_parameters(operation_parameters.chain(path_parameters))
-
-          build_requests(path:, request_method:, operation_object:,
-                         parameters:).each do |request|
-            router.add_request(
-              request,
-              request_method:,
-              path:,
-              content_type: request.content_type,
-              allow_empty_content: request.allow_empty_content?
-            )
-            build_responses(request:, responses: operation_object['responses']).each do |response|
-              router.add_response(
-                response,
-                request_method:,
-                path:,
-                status: response.status,
-                response_content_type: response.content_type
-              )
-            end
-          end
+          register_operation(router, path:, request_method:, operation_object:, path_parameters:)
+        end
+
+        path_item_object['additionalOperations']&.each do |request_method, operation_object|
+          register_operation(router, path:, request_method: request_method.downcase,
+                                     operation_object:, path_parameters:)
         end
       end
       router
     end
 
+    def register_operation(router, path:, request_method:, operation_object:, path_parameters:)
+      operation_parameters = operation_object['parameters'] || []
+      parameters = parse_parameters(operation_parameters.chain(path_parameters))
+
+      build_requests(path:, request_method:, operation_object:,
+                     parameters:).each do |request|
+        router.add_request(
+          request,
+          request_method:,
+          path:,
+          content_type: request.content_type,
+          allow_empty_content: request.allow_empty_content?
+        )
+        register_responses(router, request:, path:, request_method:,
+                                   responses: operation_object['responses'])
+      end
+    end
+
+    def register_responses(router, request:, path:, request_method:, responses:)
+      build_responses(request:, responses:).each do |response|
+        router.add_response(
+          response,
+          request_method:,
+          path:,
+          status: response.status,
+          response_content_type: response.content_type
+        )
+      end
+    end
+
     def parse_parameters(parameters)
-      grouped_parameters = group_parameters(parameters)
+      grouped = group_parameters(parameters)
+      path = build_parameters(grouped[:path])
+      query = build_parameters(grouped[:query])
+      header = build_parameters(grouped[:header])
+      cookie = build_parameters(grouped[:cookie])
       ParsedParameters.new(
-        query: resolve_parameters(grouped_parameters[:query]),
-        path: resolve_parameters(grouped_parameters[:path]),
-        cookie: resolve_parameters(grouped_parameters[:cookie]),
-        header: resolve_parameters(grouped_parameters[:header]),
-        query_schema: build_parameter_schema(grouped_parameters[:query]),
-        path_schema: build_parameter_schema(grouped_parameters[:path]),
-        cookie_schema: build_parameter_schema(grouped_parameters[:cookie]),
-        header_schema: build_parameter_schema(grouped_parameters[:header])
+        all: [*path, *query, *header, *cookie].freeze,
+        path_parser: grouped[:path] && ParametersParser.new(path),
+        query_parser: QueryStringParser.new(query),
+        header_parser: grouped[:header] && ParametersParser.new(header),
+        cookie_parser: grouped[:cookie] && ParametersParser.new(cookie),
+        path_schema: build_parameter_schema(grouped[:path]),
+        query_schema: build_parameter_schema(grouped[:query]),
+        header_schema: build_parameter_schema(grouped[:header]),
+        cookie_schema: build_parameter_schema(grouped[:cookie])
       )
     end
 
-    def resolve_parameters(parameters)
-      parameters&.map do |parameter|
-        result = parameter.resolved
-        _media_type, media_type_object = parameter['content']&.first
-        result['schema'] = (media_type_object || parameter)['schema'].resolved
-        result
-      end.to_a
+    def build_parameters(parameters)
+      parameters.to_a.map do |parameter|
+        Parameter.new(parameter.resolved, schema: parameter_schema_node(parameter)&.dereferenced)
+      end
+    end
+
+    # The schema of a parameter is either defined directly or inside a content media type object
+    def parameter_schema_node(parameter)
+      _media_type, media_type_object = parameter['content']&.first
+      (media_type_object || parameter)['schema']
     end
 
     def build_parameter_schema(parameters)
@@ -121,7 +154,7 @@ module OpenapiFirst
 
       required = []
       schemas = parameters.each_with_object({}) do |parameter, result|
-        schema = parameter['schema'].schema(configuration: schemer_configuration)
+        schema = parameter_schema_node(parameter)&.schema(configuration: schemer_configuration)
         name = parameter['name']&.value
         required << name if parameter['required']&.value
         result[name] = schema if schema
@@ -193,16 +226,18 @@ module OpenapiFirst
 
       result = []
       headers_object.each do |name, header|
-        next if header['schema'].nil?
+        schema_node = header['schema']
+        next if schema_node.nil?
         next if IGNORED_HEADER_PARAMETERS.include?(name)
 
-        header = Header.new(
+        required = header['required']&.value == true
+        result << ResponseHeader.new(
           name:,
-          schema: header['schema'].schema(configuration: schemer_configuration),
-          required?: header['required']&.value == true,
-          node: header
+          schema: schema_node.schema(configuration: schemer_configuration),
+          required?: required,
+          parameter: Parameter.new({ 'name' => name, 'in' => 'header', 'required' => required },
+                                   schema: schema_node.dereferenced)
         )
-        result << header
       end
       result
     end
@@ -216,8 +251,8 @@ module OpenapiFirst
       result
     end
 
-    ParsedParameters = Data.define(:path, :query, :header, :cookie, :path_schema, :query_schema, :header_schema,
-                                   :cookie_schema)
+    ParsedParameters = Data.define(:all, :path_parser, :query_parser, :header_parser, :cookie_parser,
+                                   :path_schema, :query_schema, :header_schema, :cookie_schema)
     private_constant :ParsedParameters
   end
 end

data/lib/openapi_first/child_configuration.rb

@@ -7,8 +7,6 @@ module OpenapiFirst
       super()
       @parent = parent
       @request_validation_error_response = parent.request_validation_error_response
-      @request_validation_raise_error = parent.request_validation_raise_error
-      @response_validation_raise_error = parent.response_validation_raise_error
       @path = parent.path
     end
 

data/lib/openapi_first/configuration.rb

@@ -14,8 +14,6 @@ module OpenapiFirst
 
     def initialize
       @request_validation_error_response = OpenapiFirst.find_error_response(:default)
-      @request_validation_raise_error = false
-      @response_validation_raise_error = true
       @hooks = HOOKS.to_h { [_1, Set.new] }
       @path = nil
     end
@@ -27,11 +25,6 @@ module OpenapiFirst
     attr_reader :hooks, :request_validation_error_response
     attr_accessor :path
 
-    # @deprecated
-    attr_reader :request_validation_raise_error
-    # @deprecated
-    attr_reader :response_validation_raise_error
-
     # Return a child configuration that still receives updates of global hooks.
     def child
       ChildConfiguration.new(parent: self)
@@ -42,22 +35,6 @@ module OpenapiFirst
       raise NoMethodError, 'OpenapiFirst::Configuration#clone was removed. You want to call #child instead'
     end
 
-    # @deprecated Pass `raise_error:` to OpenapiFirst::Middlewares::RequestValidation directly
-    def request_validation_raise_error=(value)
-      message = 'Setting OpenapiFirst::Configuration#request_validation_raise_error will be removed. ' \
-                'Please pass `raise_error:` to `OpenapiFirst::Middlewares::RequestValidation directly`'
-      warn message, category: :deprecated
-      @request_validation_raise_error = value
-    end
-
-    # @deprecated Pass `raise_error:` to OpenapiFirst::Middlewares::ResponseValidation directly
-    def response_validation_raise_error=(value)
-      message = 'Setting OpenapiFirst::Configuration#request_validation_raise_error will be removed. ' \
-                'Please pass `raise_error:` to `OpenapiFirst::Middlewares::ResponseValidation directly`'
-      warn message
-      @response_validation_raise_error = value
-    end
-
     HOOKS.each do |hook|
       define_method(hook) do |&block|
         return hooks[hook] if block.nil?

data/lib/openapi_first/definition.rb

@@ -71,15 +71,40 @@ module OpenapiFirst
       "#<#{self.class.name} @key='#{key}'>"
     end
 
+    # Resolves the path for the named operation, filling in any `{param}` placeholders.
+    # @param operation_id [String, Symbol] An operationId present in this API description.
+    # @param params [Hash] Path-parameter values keyed by name (String or Symbol).
+    # @return [String] The resolved path (e.g. "/pets/42").
+    # @raise [ArgumentError] if the operationId is not found or a required path parameter is missing.
+    def path_for(params = {}, operation_id:)
+      request_def = routes.lazy.flat_map(&:requests).find { |r| r.operation_id == operation_id.to_s }
+      raise ArgumentError, "Operation #{operation_id.inspect} is not defined in #{key}." unless request_def
+
+      request_def.path.gsub(/\{([^}]+)\}/) do
+        name = Regexp.last_match(1)
+        params.fetch(name.to_sym) do
+          params.fetch(name) do
+            raise ArgumentError, "Missing path parameter #{name.inspect} for operation #{operation_id.inspect}."
+          end
+        end
+      end
+    end
+
     # Validates the request against the API description.
     # @param [Rack::Request] request The Rack request object.
     # @param [Boolean] raise_error Whether to raise an error if validation fails.
+    # @param [String,nil] path_template The OpenAPI path template (e.g. "/pets/{petId}") of the
+    #   already-matched route. Pass this when your own router has matched the route, to skip
+    #   openapi_first's path matching. Used by framework integrations like Sinatra.
+    # @param [Hash,nil] path_params The path parameters extracted by your own router
+    #   (e.g. { "petId" => "42" }), keyed by parameter name. Pass this together with +path_template+
+    #   to skip openapi_first's path-parameter extraction; otherwise they are extracted from the path.
     # @yield [ValidatedRequest] Optional block called after successful validation.
     #   The block runs inside the same catch(FAILURE) as the after_request_validation hooks,
     #   so it may call OpenapiFirst::Failure.fail! to short-circuit and produce an error.
     # @return [ValidatedRequest] The validated request object.
-    def validate_request(request, raise_error: false, &after_block)
-      route = @router.match(request.request_method, resolve_path(request), content_type: request.content_type)
+    def validate_request(request, raise_error: false, path_template: nil, path_params: nil, &after_block)
+      route = match_route(request, path_template, params: path_params)
       validated = if route.error
                     ValidatedRequest.new(request, error: route.error)
                   else
@@ -117,6 +142,14 @@ module OpenapiFirst
 
     private
 
+    def match_route(request, path_template, params:)
+      request_method = request.request_method
+      content_type = request.content_type
+      return @router.match_route(request_method, path_template, params:, content_type:) if path_template
+
+      @router.match(request_method, resolve_path(request), content_type:)
+    end
+
     def call_before_request_validation_hooks(request, request_definition)
       return if @config.before_request_validation.none?
 

data/lib/openapi_first/failure.rb

@@ -3,7 +3,7 @@
 module OpenapiFirst
   # A failure object returned when validation or parsing of a request or response has failed.
   # This returned in ValidatedRequest#error and ValidatedResponse#error.
-  class Failure < Data.define(:type, :message, :errors) # rubocop:disable Style/DataInheritance
+  class Failure < Data.define(:type, :message, :errors)
     TYPES = {
       not_found: [NotFoundError, 'Not found.'],
       method_not_allowed: [RequestInvalidError, 'Request method is not defined.'],
@@ -49,6 +49,10 @@ module OpenapiFirst
     alias original_message message
     private :original_message
 
+    def inspect
+      "#<OpenapiFirst::Failure:#{object_id} type: #{type}, message: #{message}>"
+    end
+
     # A generic error message
     def message
       original_message || exception_message

data/lib/openapi_first/middlewares/request_validation.rb

@@ -36,7 +36,7 @@ module OpenapiFirst
           options = spec
           spec = options[:spec]
         end
-        @raise = options.fetch(:raise_error, OpenapiFirst.configuration.request_validation_raise_error)
+        @raise = options.fetch(:raise_error, false)
         @error_response_class = error_response_option(options[:error_response])
 
         spec ||= :default