openapi_first 2.5.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf125609ca3acdca953b0ab241990d7593ac3ac1820e4dcda0b1f7f711cfd87b
-  data.tar.gz: 53c2039f9fb7f379784f08f2dbcf7e3aac3273f7cd452af17227ccb2b896ed9e
+  metadata.gz: 177998c88421283a6868e3aa9c5bbbe1eea702bc8b65abb22c28795cb2b7b6a2
+  data.tar.gz: 603118b530e39957ea95086d98a95362e9eb9b9490a63adc7c2bc8e0f7ba7846
 SHA512:
-  metadata.gz: 89f5dce609ef24d0ef739b887e42604784e7849395c967bce6f4f79084d5e35ef9f63608c3c328dc5825ffb668cc68c934290195f20edb8ace5bbf6d6adb6e26
-  data.tar.gz: 9716f7808d362cec5e6261abc67c05082a7a6b997eed96a3e74b9e58172579f2f8a80464b20699b8f8a5c8d875d1cb3eaee57bf6300d971b6ad9bc6484f8d04b
+  metadata.gz: 58aac32a5c8d7433414f4bf0f2cbf8142376c76d9ad918bf06531f40da0206e870a12e36718ca7763dd273ea18b664799f22acff84df143e36591a19284895fd
+  data.tar.gz: cba873da9fa8b1bf957a47fe34dcd30c50af51185dc83ba78c3f78ad2d5630399555c7d81f89f6e7cb96d9c56771c55aa956900249c2a6700d88869233339f6d

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 2.7.0
+
+- Allow to override path for schema matching with `config.path = ->(request) { '/prefix' + request.path  } ` (https://github.com/ahx/openapi_first/issues/349)
+- Support passing in a Definition instance when registering an OAD for tests (https://github.com/ahx/openapi_first/issues/353)
+- Fix registering multiple APIs for testing (https://github.com/ahx/openapi_first/issues/352)
+
+## 2.6.0
+
+- Middlewares now accept the OAD as a first positional argument instead of `:spec` inside the options hash.
+- No longer merge parameter schemas of the same location (for example "query") in order to fix [#320](https://github.com/ahx/openapi_first/issues/320).
+- `OpenapiFirst::Test::Methods[MyApplication]` returns a Module which adds an `app` method to be used by rack-test alonside the `assert_api_conform` method.
+- Make default coverage report less verbose
+  The default formatter (TerminalFormatter) no longer prints all un-requested requests by default. You can set `test.coverage_formatter_options = { focused: false }` to get back the old behavior
+
 ## 2.5.1
 
 - Fix skipping skipped responses during coverage tracking

data/README.md

@@ -19,6 +19,7 @@ You can use openapi_first on production for [request validation](#request-valida
 - [Configuration](#configuration)
 - [Hooks](#hooks)
 - [Alternatives](#alternatives)
+- [Frequently Asked Questions](#frequently-asked-questions)
 - [Development](#development)
   - [Benchmarks](#benchmarks)
   - [Contributing](#contributing)
@@ -29,13 +30,13 @@ You can use openapi_first on production for [request validation](#request-valida
 
 ### Request validation
 
-The request validation middleware returns a 4xx if the request is invalid or not defined in the API description. It adds a request object to the current Rack environment at `env[OpenapiFirst::REQUEST]` with the request parameters parsed exaclty as described in your API description plus access to meta information from your API description. See _[Manual use](#manual-use)_ for more details about that object.
+The request validation middleware returns a 4xx if the request is invalid or not defined in the API description. It adds a request object to the current Rack environment at `env[OpenapiFirst::REQUEST]` with the request parameters parsed exactly as described in your API description plus access to meta information from your API description. See _[Manual use](#manual-use)_ for more details about that object.
 
 ```ruby
-use OpenapiFirst::Middlewares::RequestValidation, spec: 'openapi.yaml'
+use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml'
 
 # Pass `raise_error: true` to raise an error if request is invalid:
-use OpenapiFirst::Middlewares::RequestValidation, raise_error: true, spec: 'openapi.yaml'
+use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml', raise_error: true
 ```
 
 #### Error responses
@@ -73,7 +74,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, spec: 'openapi.yaml, error_response: :jsonapi'
+use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml, error_response: :jsonapi'
 ```
 
 <details>
@@ -126,45 +127,57 @@ 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
-use OpenapiFirst::Middlewares::ResponseValidation, spec: 'openapi.yaml' if ENV['RACK_ENV'] == 'test'
+use OpenapiFirst::Middlewares::ResponseValidation, 'openapi.yaml' if ENV['RACK_ENV'] == 'test'
 
 # Pass `raise_error: false` to not raise an error:
-use OpenapiFirst::Middlewares::ResponseValidation, raise_error: false, spec: 'openapi.yaml'
+use OpenapiFirst::Middlewares::ResponseValidation, 'openapi.yaml', 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.
 
 ## Contract Testing
 
+Here are two aspects of contract testing: Validation and Coverage
+
+### Validation
+
+By validating requests and responses, you can avoid that your API implementation processes requests or returns responses that don't match your API description. You can use [test assertions](#test-assertions) or [rack middlewares](#rack-middlewares) or manual validation to validate requests and responses with openapi_first.
+
 ### Coverage
 
+To make sure your _whole_ API description is implemented, openapi_first ships with a coverage feature.
+
 > [!NOTE]
 > This is a brand new feature. ✨ Your feedback is very welcome.
 
-This feature tracks all requests/resposes that are validated via openapi_first and get return an overal coverage value. If all of your described requests/responses have been validated successfully at least once, your coverage is 100%.
-By checking your validation coverage you can avoid API drift where your API description describes requests/responses differently than your implemention works.
-
-Here is how to set it up for RSpec in your `spec/spec_helper.rb`:
+This feature tracks all requests/responses that are validated via openapi_first and tells you about which request/responses are missing.
+Here is how to set it up with [rack-test](https://github.com/rack/rack-test):
 
-1. Register all OpenAPI documents to track coverage for and start tracking. This should go at the top of you test helper file before loading application code.
+1. Register all OpenAPI documents to track coverage for. This should go at the top of your test helper file before loading your application code.
   ```ruby
   require 'openapi_first'
-  OpenapiFirst::Test.setup do |s|
+  OpenapiFirst::Test.setup do |test|
     test.register('openapi/openapi.yaml')
-    test.minimum_coverage = 100 # Setting this will lead to an `exit 2` if coverage is below minimum
-    test.skip_response_coverage { it.status == '500' }
+    test.minimum_coverage = 100 # (Optional) Setting this will lead to an `exit 2` if coverage is below minimum
+    test.skip_response_coverage { it.status == '500' } # (Optional) Skip certain responses
   end
   ```
-2. Wrap your app with silent request / response validation. This validates all requets/responses you do during your test run. (✷1)
+2. Add an `app` method to your tests, which wraps your application with silent request / response validation. This validates all requests/responses in your test run. (✷1)
+
   ```ruby
-  config.before type: :request do
-    def app
-      OpenapiFirst::Test.app(App)
-    end
+  def app
+    OpenapiFirst::Test.app(MyApp)
   end
   ```
+3. Run your tests.  The Coverage feature will tell you about missing request/responses.
+
+  Or you can generate a Module and include it in your rspec spec_helper.rb:
+
+  ```ruby
+  config.include OpenapiFirst::Test::Methods[MyApp], type: :request
+  ```
 
-(✷1): Instead of using `OpenapiFirstTest.app` to wrap your application, you can use the middlewares or [test assertion method](#test-assertions), but you would have to do that for all requests/responses defined in your API description to make coverage work.
+(✷1): It does not matter what method of openapi_first you use to validate requests/responses. Instead of using `OpenapiFirstTest.app` to wrap your application, you could also use the middlewares or [test assertion method](#test-assertions), but you would have to do that for all requests/responses defined in your API description to make coverage work.
 
 ### Test assertions
 
@@ -296,7 +309,7 @@ Setup globally:
 ```ruby
 OpenapiFirst.configure do |config|
   config.after_request_parameter_property_validation do |data, property, property_schema|
-    data[property] = Date.iso8601(data[property]) if propert_schema['format'] == 'date'
+    data[property] = Date.iso8601(data[property]) if property_schema['format'] == 'date'
   end
 end
 ```
@@ -306,11 +319,40 @@ end
 Using rack middlewares is supported in probably all Ruby web frameworks.
 If you are using Ruby on Rails for example, you can add the request validation middleware globally in `config/application.rb` or inside specific controllers.
 
+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 Rails would be great. If you have ideas, pain points or PRs, please don't hesitate to [share](https://github.com/ahx/openapi_first/discussions).
+
 ## Alternatives
 
-This gem was inspired by [committe](https://github.com/interagent/committee) (Ruby) and [Connexion](https://github.com/spec-first/connexion) (Python).
+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
+
+### How can I adapt request paths that don't match my schema?
+
+If your API is deployed at a different path than what's defined in your OpenAPI schema, you can use `env[OpenapiFirst::PATH]` to override the path used for schema matching.
+
+Let's say you have `openapi.yaml` like this:
+
+```yaml
+servers:
+  - url: https://yourhost/api
+paths:
+  # The actual endpoint URL is https://yourhost/api/resource
+  /resource:
+```
+
+Here your OpenAPI schema defines endpoints starting with `/resource` but your actual application is mounted at `/api/resource`. You can bridge the gap by transforming the path via the `path:` configuration:
+
+```ruby
+oad = OpenapiFirst.load('openapi.yaml') do |config|
+  config.path = ->(req) { request.path.delete_prefix('/api') }
+end
+use OpenapiFirst::Middlewares::RequestValidation, oad
+```
+
 ## Development
 
 Run `bin/setup` to install dependencies.

data/lib/openapi_first/builder.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 require 'json_schemer'
+
+require_relative 'failure'
+require_relative 'router'
+require_relative 'header'
+require_relative 'request'
+require_relative 'response'
+require_relative 'schema/hash'
 require_relative 'ref_resolver'
 
 module OpenapiFirst
@@ -17,10 +24,8 @@ module OpenapiFirst
     end
 
     def initialize(contents, filepath:, config:)
-      @schemer_configuration = JSONSchemer.configuration.clone
-      @schemer_configuration.meta_schema = detect_meta_schema(contents, filepath)
-      @schemer_configuration.insert_property_defaults = true
-
+      meta_schema = detect_meta_schema(contents, filepath)
+      @schemer_configuration = build_schemer_config(filepath:, meta_schema:)
       @config = config
       @contents = RefResolver.for(contents, filepath:)
     end
@@ -28,15 +33,25 @@ module OpenapiFirst
     attr_reader :config
     private attr_reader :schemer_configuration
 
+    def build_schemer_config(filepath:, meta_schema:)
+      result = JSONSchemer.configuration.clone
+      dir = (filepath && File.absolute_path(File.dirname(filepath))) || Dir.pwd
+      result.base_uri = URI::File.build({ path: "#{dir}/" })
+      result.ref_resolver = JSONSchemer::CachedResolver.new do |uri|
+        FileLoader.load(uri.path)
+      end
+      result.meta_schema = meta_schema
+      result.insert_property_defaults = true
+      result
+    end
+
     def detect_meta_schema(document, filepath)
       # Copied from JSONSchemer 🙇🏻‍♂️
       version = document['openapi']
       case version
       when /\A3\.1\.\d+\z/
-        @document_schema = JSONSchemer.openapi31_document
         document.fetch('jsonSchemaDialect') { JSONSchemer::OpenAPI31::BASE_URI.to_s }
       when /\A3\.0\.\d+\z/
-        @document_schema = JSONSchemer.openapi30_document
         JSONSchemer::OpenAPI30::BASE_URI.to_s
       else
         raise Error, "Unsupported OpenAPI version #{version.inspect} #{filepath}"
@@ -46,10 +61,10 @@ module OpenapiFirst
     def router # rubocop:disable Metrics/MethodLength
       router = OpenapiFirst::Router.new
       @contents.fetch('paths').each do |path, path_item_object|
-        path_parameters = resolve_parameters(path_item_object['parameters'])
+        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 = resolve_parameters(operation_object['parameters'])
+          operation_parameters = operation_object['parameters'] || []
           parameters = parse_parameters(operation_parameters.chain(path_parameters))
 
           build_requests(path:, request_method:, operation_object:,
@@ -79,10 +94,10 @@ module OpenapiFirst
     def parse_parameters(parameters)
       grouped_parameters = group_parameters(parameters)
       ParsedParameters.new(
-        query: grouped_parameters[:query],
-        path: grouped_parameters[:path],
-        cookie: grouped_parameters[:cookie],
-        header: grouped_parameters[:header],
+        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]),
@@ -99,11 +114,18 @@ module OpenapiFirst
     end
 
     def build_parameter_schema(parameters)
-      schema = build_parameters_schema(parameters)
+      return unless parameters
 
-      JSONSchemer.schema(schema,
-                         configuration: schemer_configuration,
-                         after_property_validation: config.hooks[:after_request_parameter_property_validation])
+      required = []
+      schemas = parameters.each_with_object({}) do |parameter, result|
+        schema = parameter['schema'].schema(configuration: schemer_configuration)
+        name = parameter['name']&.value
+        required << name if parameter['required']&.value
+        result[name] = schema if schema
+      end
+
+      Schema::Hash.new(schemas, required:, configuration: schemer_configuration,
+                                after_property_validation: config.hooks[:after_request_parameter_property_validation])
     end
 
     def build_requests(path:, request_method:, operation_object:, parameters:)
@@ -141,20 +163,15 @@ module OpenapiFirst
       return [] unless responses
 
       responses.flat_map do |status, response_object|
-        headers = response_object['headers']&.resolved
-        headers_schema = JSONSchemer::Schema.new(
-          build_headers_schema(headers),
-          configuration: schemer_configuration
-        )
+        headers = build_response_headers(response_object['headers'])
         response_object['content']&.map do |content_type, content_object|
           content_schema = content_object['schema'].schema(configuration: schemer_configuration)
           Response.new(status:,
                        headers:,
-                       headers_schema:,
                        content_type:,
                        content_schema:,
                        key: [request.key, status, content_type].join(':'))
-        end || Response.new(status:, headers:, headers_schema:, content_type: nil,
+        end || Response.new(status:, headers:, content_type: nil,
                             content_schema: nil, key: [request.key, status, nil].join(':'))
       end
     end
@@ -162,49 +179,32 @@ module OpenapiFirst
     IGNORED_HEADER_PARAMETERS = Set['Content-Type', 'Accept', 'Authorization'].freeze
     private_constant :IGNORED_HEADER_PARAMETERS
 
-    def group_parameters(parameter_definitions)
-      result = {}
-      parameter_definitions&.each do |parameter|
-        (result[parameter['in'].to_sym] ||= []) << parameter
-      end
-      result[:header]&.reject! { IGNORED_HEADER_PARAMETERS.include?(_1['name']) }
-      result
-    end
-
-    def build_headers_schema(headers_object)
-      return unless headers_object&.any?
+    def build_response_headers(headers_object)
+      return if headers_object.nil?
 
-      properties = {}
-      required = []
+      result = []
       headers_object.each do |name, header|
-        schema = header['schema']
-        next if name.casecmp('content-type').zero?
-
-        properties[name] = schema if schema
-        required << name if header['required']
+        next if header['schema'].nil?
+        next if IGNORED_HEADER_PARAMETERS.include?(name)
+
+        header = Header.new(
+          name:,
+          schema: header['schema'].schema(configuration: schemer_configuration),
+          required?: header['required']&.value == true,
+          node: header
+        )
+        result << header
       end
-      {
-        'properties' => properties,
-        'required' => required
-      }
+      result
     end
 
-    def build_parameters_schema(parameters)
-      return unless parameters
-
-      properties = {}
-      required = []
-      parameters.each do |parameter|
-        schema = parameter['schema']
-        name = parameter['name']
-        properties[name] = schema if schema
-        required << name if parameter['required']
+    def group_parameters(parameter_definitions)
+      result = {}
+      parameter_definitions&.each do |parameter|
+        (result[parameter['in']&.value&.to_sym] ||= []) << parameter
       end
-
-      {
-        'properties' => properties,
-        'required' => required
-      }
+      result[:header]&.reject! { IGNORED_HEADER_PARAMETERS.include?(_1['name']&.value) }
+      result
     end
 
     ParsedParameters = Data.define(:path, :query, :header, :cookie, :path_schema, :query_schema, :header_schema,

data/lib/openapi_first/configuration.rb

@@ -15,10 +15,11 @@ module OpenapiFirst
       @request_validation_raise_error = false
       @response_validation_raise_error = true
       @hooks = (HOOKS.map { [_1, Set.new] }).to_h
+      @path = nil
     end
 
     attr_reader :request_validation_error_response, :hooks
-    attr_accessor :request_validation_raise_error, :response_validation_raise_error
+    attr_accessor :request_validation_raise_error, :response_validation_raise_error, :path
 
     def clone
       copy = super

data/lib/openapi_first/definition.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'failure'
-require_relative 'router'
-require_relative 'request'
-require_relative 'response'
 require_relative 'builder'
 require 'forwardable'
 
@@ -44,12 +40,30 @@ module OpenapiFirst
     # @return [Enumerable[Router::Route]]
     def_delegators :@router, :routes
 
+    # Returns a unique identifier for this API definition
+    # @return [String] A unique key for this API definition
+    def key
+      return filepath if filepath
+
+      info = self['info'] || {}
+      title = info['title']
+      version = info['version']
+
+      if title.nil? || version.nil?
+        raise ArgumentError,
+              "Cannot generate key for the OpenAPI document because 'info.title' or 'info.version' is missing. " \
+              'Please add these fields to your OpenAPI document.'
+      end
+
+      "#{title} @ #{version}"
+    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.
     # @return [ValidatedRequest] The validated request object.
     def validate_request(request, raise_error: false)
-      route = @router.match(request.request_method, request.path, content_type: request.content_type)
+      route = @router.match(request.request_method, resolve_path(request), content_type: request.content_type)
       if route.error
         ValidatedRequest.new(request, error: route.error)
       else
@@ -66,7 +80,8 @@ module OpenapiFirst
     # @param raise_error [Boolean] Whethir to raise an error if validation fails.
     # @return [ValidatedResponse] The validated response object.
     def validate_response(rack_request, rack_response, raise_error: false)
-      route = @router.match(rack_request.request_method, rack_request.path, content_type: rack_request.content_type)
+      route = @router.match(rack_request.request_method, resolve_path(rack_request),
+                            content_type: rack_request.content_type)
       return if route.error # Skip response validation for unknown requests
 
       response_match = route.match_response(status: rack_response.status, content_type: rack_response.content_type)
@@ -80,5 +95,13 @@ module OpenapiFirst
         raise validated.error.exception(validated) if raise_error && validated.invalid?
       end
     end
+
+    private
+
+    def resolve_path(rack_request)
+      return rack_request.path unless @config.path
+
+      @config.path.call(rack_request)
+    end
   end
 end

data/lib/openapi_first/header.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  Header = Data.define(:name, :required?, :schema, :node) do
+    def resolved_schema
+      node['schema']&.resolved
+    end
+  end
+end

data/lib/openapi_first/middlewares/request_validation.rb

@@ -6,19 +6,26 @@ module OpenapiFirst
     # A Rack middleware to validate requests against an OpenAPI API description
     class RequestValidation
       # @param app The parent Rack application
-      # @param options An optional Hash of configuration options to override defaults
+      # @param spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      # @param options Hash
+      #   :spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #         This will be deprecated. Please use spec argument instead.
       #   :raise_error    A Boolean indicating whether to raise an error if validation fails.
       #                   default: false
       #   :error_response The Class to use for error responses.
       #                   This can be a Symbol-name of an registered error response (:default, :jsonapi)
       #                   or it can be set to false to disable returning a response.
       #                   default: OpenapiFirst::Plugins::Default::ErrorResponse (Config.default_options.error_response)
-      def initialize(app, options = {})
+      def initialize(app, spec = nil, options = {})
         @app = app
+        if spec.is_a?(Hash)
+          options = spec
+          spec = options.fetch(:spec)
+        end
         @raise = options.fetch(:raise_error, OpenapiFirst.configuration.request_validation_raise_error)
         @error_response_class = error_response_option(options[:error_response])
 
-        spec = options.fetch(:spec)
+        spec ||= options.fetch(:spec)
         raise "You have to pass spec: when initializing #{self.class}" unless spec
 
         @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)

data/lib/openapi_first/middlewares/response_validation.rb

@@ -6,15 +6,19 @@ module OpenapiFirst
   module Middlewares
     # A Rack middleware to validate requests against an OpenAPI API description
     class ResponseValidation
-      # @param app The parent Rack application
+      # @param spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition
       # @param options Hash
-      #   :spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition
+      #   :spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #         This will be deprecated. Please use spec argument instead.
       #   :raise_error [Boolean] Whether to raise an error if validation fails. default: true
-      def initialize(app, options = {})
+      def initialize(app, spec = nil, options = {})
         @app = app
+        if spec.is_a?(Hash)
+          options = spec
+          spec = options.fetch(:spec)
+        end
         @raise = options.fetch(:raise_error, OpenapiFirst.configuration.response_validation_raise_error)
 
-        spec = options.fetch(:spec)
         raise "You have to pass spec: when initializing #{self.class}" unless spec
 
         @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)
@@ -25,7 +29,8 @@ module OpenapiFirst
 
       def call(env)
         status, headers, body = @app.call(env)
-        @definition.validate_response(Rack::Request.new(env), Rack::Response[status, headers, body], raise_error: @raise)
+        @definition.validate_response(Rack::Request.new(env), Rack::Response[status, headers, body],
+                                      raise_error: @raise)
         [status, headers, body]
       end
     end

data/lib/openapi_first/ref_resolver.rb

@@ -41,8 +41,11 @@ module OpenapiFirst
         @value = value
         @context = context
         @filepath = filepath
-        dir = File.dirname(File.expand_path(filepath)) if filepath
-        @dir = (dir && File.absolute_path(dir)) || Dir.pwd
+        @dir = if filepath
+                 File.dirname(File.absolute_path(filepath))
+               else
+                 Dir.pwd
+               end
       end
 
       # The value of this node
@@ -52,7 +55,11 @@ module OpenapiFirst
       # The object where this node was found in
       attr_reader :context
 
-      private attr_reader :filepath
+      attr_reader :filepath
+
+      def ==(_other)
+        raise "Don't call == on an unresolved value. Use .value == other instead."
+      end
 
       def resolve_ref(pointer)
         if pointer.start_with?('#')
@@ -89,6 +96,10 @@ module OpenapiFirst
       include Diggable
       include Enumerable
 
+      def ==(_other)
+        raise "Don't call == on an unresolved value. Use .value == other instead."
+      end
+
       def resolved
         return resolve_ref(value['$ref']).value if value.key?('$ref')
 
@@ -108,17 +119,16 @@ module OpenapiFirst
       end
 
       def each
-        resolved.each do |key, value|
-          yield key, RefResolver.for(value, filepath:, context:)
+        resolved.each_key do |key|
+          yield key, self[key]
         end
       end
 
-      def schema(options = {})
-        ref_resolver = JSONSchemer::CachedResolver.new do |uri|
-          FileLoader.load(uri.path)
-        end
+      # You have to pass configuration or ref_resolver
+      def schema(options)
         base_uri = URI::File.build({ path: "#{dir}/" })
-        root = JSONSchemer::Schema.new(context, base_uri:, ref_resolver:, **options)
+        root = JSONSchemer::Schema.new(context, base_uri:, **options)
+        # binding.irb if value['maxItems'] == 4
         JSONSchemer::Schema.new(value, nil, root, base_uri:, **options)
       end
     end
@@ -137,8 +147,8 @@ module OpenapiFirst
       end
 
       def each
-        resolved.each do |item|
-          yield RefResolver.for(item, filepath:, context:)
+        resolved.each_with_index do |_item, index|
+          yield self[index]
         end
       end
 

data/lib/openapi_first/response.rb

@@ -9,21 +9,20 @@ module OpenapiFirst
   # This is not a direct reflecton of the OpenAPI 3.X response definition, but a combination of
   # status, content type and content schema.
   class Response
-    def initialize(status:, headers:, headers_schema:, content_type:, content_schema:, key:)
+    def initialize(status:, headers:, content_type:, content_schema:, key:)
       @status = status
       @content_type = content_type
       @content_schema = content_schema
       @headers = headers
-      @headers_schema = headers_schema
       @key = key
       @parser = ResponseParser.new(headers:, content_type:)
-      @validator = ResponseValidator.new(self)
+      @validator = ResponseValidator.new(content_schema:, headers:)
     end
 
     # @attr_reader [Integer] status The HTTP status code of the response definition.
     # @attr_reader [String, nil] content_type Content type of this response.
     # @attr_reader [Schema, nil] content_schema the Schema of the response body.
-    attr_reader :status, :content_type, :content_schema, :headers, :headers_schema, :key
+    attr_reader :status, :content_type, :content_schema, :headers, :key
 
     def validate(response)
       parsed_values = nil

data/lib/openapi_first/response_parser.rb

@@ -15,7 +15,7 @@ module OpenapiFirst
     def parse(rack_response)
       ParsedResponse.new(
         body: @body_parser.call(read_body(rack_response)),
-        headers: @headers_parser.call(rack_response.headers)
+        headers: @headers_parser&.call(rack_response.headers) || {}
       )
     end
 
@@ -30,9 +30,16 @@ module OpenapiFirst
       rack_response.body
     end
 
-    def build_headers_parser(header_definitions)
-      headers_as_parameters = header_definitions.to_a.map do |name, definition|
-        definition.merge('name' => name, 'in' => 'header')
+    def build_headers_parser(headers)
+      return unless headers&.any?
+
+      headers_as_parameters = headers.map do |header|
+        {
+          'name' => header.name,
+          'explode' => false,
+          'in' => 'header',
+          'schema' => header.resolved_schema
+        }
       end
       OpenapiParameters::Header.new(headers_as_parameters).method(:unpack)
     end

data/lib/openapi_first/response_validator.rb

@@ -11,10 +11,10 @@ module OpenapiFirst
       Validators::ResponseBody
     ].freeze
 
-    def initialize(response_definition)
-      @validators = VALIDATORS.filter_map do |klass|
-        klass.for(response_definition)
-      end
+    def initialize(content_schema:, headers:)
+      @validators = []
+      @validators << Validators::ResponseBody.new(content_schema) if content_schema
+      @validators << Validators::ResponseHeaders.new(headers) if headers&.any?
     end
 
     def call(parsed_response)

data/lib/openapi_first/schema/hash.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'validation_error'
+
+module OpenapiFirst
+  class Schema
+    # A hash of Schemas
+    class Hash
+      # @param schema Hash of schemas
+      # @param required Array of required keys
+      def initialize(schemas, required: nil, **options)
+        @schemas = schemas
+        @options = options
+        @after_property_validation = options.delete(:after_property_validation)
+        schema = { 'type' => 'object' }
+        schema['required'] = required if required
+        @root_schema = JSONSchemer.schema(schema, **options)
+      end
+
+      def validate(root_value)
+        validation = @root_schema.validate(root_value)
+        validations = @schemas.reduce(validation) do |enum, (key, schema)|
+          root_value[key] = schema.value['default'] if schema.value.key?('default') && !root_value.key?(key)
+          next enum unless root_value.key?(key)
+
+          value = root_value[key]
+          key_validation = schema.validate(value)
+          @after_property_validation&.each do |hook|
+            hook.call(root_value, key, schema.value, nil)
+          end
+          enum.chain(key_validation.map do |err|
+            data_pointer = "/#{key}"
+            err.merge(
+              'error' => JSONSchemer::Errors.pretty(err),
+              'data_pointer' => data_pointer
+            )
+          end)
+        end
+        ValidationResult.new(validations)
+      end
+    end
+  end
+end

data/lib/openapi_first/schema/validation_error.rb

@@ -3,7 +3,44 @@
 module OpenapiFirst
   class Schema
     # One of multiple validation errors. Returned by Schema::ValidationResult#errors.
-    ValidationError = Data.define(:value, :message, :data_pointer, :schema_pointer, :type, :details, :schema) do
+    ValidationError = Data.define(:value, :data_pointer, :schema_pointer, :type, :details, :schema) do
+      # This returns an error message for this specific error.
+      # This it copied from json_schemer here to be easier to customize when passing custom data_pointers.
+      def message
+        location = data_pointer.empty? ? 'root' : "`#{data_pointer}`"
+
+        case type
+        when 'required'
+          keys = details.fetch('missing_keys', []).join(', ')
+          "object at #{location} is missing required properties: #{keys}"
+        when 'dependentRequired'
+          keys = details.fetch('missing_keys').join(', ')
+          "object at #{location} is missing required properties: #{keys}"
+        when 'string', 'boolean', 'number'
+          "value at #{location} is not a #{type}"
+        when 'array', 'object', 'integer'
+          "value at #{location} is not an #{type}"
+        when 'null'
+          "value at #{location} is not #{type}"
+        when 'pattern'
+          "string at #{location} does not match pattern: #{schema.fetch('pattern')}"
+        when 'format'
+          "value at #{location} does not match format: #{schema.fetch('format')}"
+        when 'const'
+          "value at #{location} is not: #{schema.fetch('const').inspect}"
+        when 'enum'
+          "value at #{location} is not one of: #{schema.fetch('enum')}"
+        when 'minimum'
+          "number at #{location} is less than: #{schema['minimum']}"
+        when 'maximum'
+          "number at #{location} is greater than: #{schema['maximum']}"
+        when 'readOnly'
+          "value at #{location} is `readOnly`"
+        else
+          "value at #{location} is invalid (#{type.inspect})"
+        end
+      end
+
       # @deprecated Please use {#message} instead
       def error
         warn 'OpenapiFirst::Schema::ValidationError#error is deprecated. Use #message instead.'

data/lib/openapi_first/schema/validation_result.rb

@@ -17,7 +17,6 @@ module OpenapiFirst
         @errors ||= @validation.map do |err|
           ValidationError.new(
             value: err['data'],
-            message: err['error'],
             data_pointer: err['data_pointer'],
             schema_pointer: err['schema_pointer'],
             type: err['type'],

data/lib/openapi_first/test/coverage/plan.rb

@@ -13,7 +13,7 @@ module OpenapiFirst
         class UnknownRequestError < StandardError; end
 
         def self.for(oad, skip_response: nil)
-          plan = new(filepath: oad.filepath)
+          plan = new(definition_key: oad.key, filepath: oad.filepath)
           oad.routes.each do |route|
             responses = skip_response ? route.responses.reject(&skip_response) : route.responses
             plan.add_route request_method: route.request_method,
@@ -24,13 +24,14 @@ module OpenapiFirst
           plan
         end
 
-        def initialize(filepath:)
+        def initialize(definition_key:, filepath: nil)
           @routes = []
           @index = {}
+          @api_identifier = filepath || definition_key
           @filepath = filepath
         end
 
-        attr_reader :filepath, :routes
+        attr_reader :api_identifier, :filepath, :routes
         private attr_reader :index
 
         def track_request(validated_request)

data/lib/openapi_first/test/coverage/terminal_formatter.rb

@@ -5,8 +5,9 @@ module OpenapiFirst
     module Coverage
       # This is the default formatter
       class TerminalFormatter
-        def initialize(verbose: false)
+        def initialize(verbose: false, focused: true)
           @verbose = verbose
+          @focused = focused && !verbose
         end
 
         # This takes a list of Coverage::Plan instances and outputs a String
@@ -16,7 +17,7 @@ module OpenapiFirst
           @out.string
         end
 
-        private attr_reader :out, :verbose
+        private attr_reader :out, :verbose, :focused
 
         private
 
@@ -29,15 +30,15 @@ module OpenapiFirst
         end
 
         def format_plan(plan)
-          filepath = plan.filepath
-          puts ['', "API validation coverage for #{filepath}: #{plan.coverage}%"]
+          puts ['', "API validation coverage for #{plan.api_identifier}: #{plan.coverage}%"]
           return if plan.done? && !verbose
 
           plan.routes.each do |route|
             next if route.finished? && !verbose
 
+            next if route.requests.none?(&:requested?) && focused
+
             format_requests(route.requests)
-            next if route.requests.none?(&:requested?)
 
             format_responses(route.responses)
           end

data/lib/openapi_first/test/coverage.rb

@@ -36,7 +36,7 @@ module OpenapiFirst
         def start(skip_response: nil)
           @current_run = Test.definitions.values.to_h do |oad|
             plan = Plan.for(oad, skip_response:)
-            [oad.filepath, plan]
+            [oad.key, plan]
           end
         end
 
@@ -53,11 +53,11 @@ module OpenapiFirst
         end
 
         def track_request(request, oad)
-          current_run[oad.filepath].track_request(request)
+          current_run[oad.key]&.track_request(request)
         end
 
         def track_response(response, _request, oad)
-          current_run[oad.filepath].track_response(response)
+          current_run[oad.key]&.track_response(response)
         end
 
         def result

data/lib/openapi_first/test/methods.rb

@@ -8,10 +8,53 @@ module OpenapiFirst
     # Methods to use in integration tests
     module Methods
       def self.included(base)
-        if Test.minitest?(base)
-          base.include(OpenapiFirst::Test::MinitestHelpers)
+        base.include(DefaultApiMethod)
+        base.include(AssertionMethod)
+      end
+
+      def self.[](application_under_test = nil, api: nil)
+        mod = Module.new do
+          def self.included(base)
+            base.include OpenapiFirst::Test::Methods::AssertionMethod
+          end
+        end
+
+        if api
+          mod.define_method(:openapi_first_default_api) { api }
         else
-          base.include(OpenapiFirst::Test::PlainHelpers)
+          mod.include(DefaultApiMethod)
+        end
+
+        if application_under_test
+          mod.define_method(:app) { OpenapiFirst::Test.app(application_under_test, api: openapi_first_default_api) }
+        end
+
+        mod
+      end
+
+      # Default methods
+      module DefaultApiMethod
+        # This is the default api that is used by assert_api_conform
+        # :default is the default name that is used if you don't pass an `api:` option to `OpenapiFirst::Test.register`
+        # This is overwritten if you pass an `api:` option to `include OpenapiFirst::Test::Methods[…]`
+        def openapi_first_default_api
+          klass = self.class
+          if klass.respond_to?(:metadata) && klass.metadata[:api]
+            klass.metadata[:api]
+          else
+            :default
+          end
+        end
+      end
+
+      # @visibility private
+      module AssertionMethod
+        def self.included(base)
+          if Test.minitest?(base)
+            base.include(OpenapiFirst::Test::MinitestHelpers)
+          else
+            base.include(OpenapiFirst::Test::PlainHelpers)
+          end
         end
       end
     end

data/lib/openapi_first/test/minitest_helpers.rb

@@ -5,7 +5,7 @@ module OpenapiFirst
     # Assertion methods for Minitest
     module MinitestHelpers
       # :nocov:
-      def assert_api_conform(status: nil, api: :default)
+      def assert_api_conform(status: nil, api: openapi_first_default_api)
         api = OpenapiFirst::Test[api]
         request = respond_to?(:last_request) ? last_request : @request
         response = respond_to?(:last_response) ? last_response : @response

data/lib/openapi_first/test/plain_helpers.rb

@@ -5,7 +5,7 @@ module OpenapiFirst
     # Assertion methods to use when no known test framework was found
     # These methods just raise an exception if an error was found
     module PlainHelpers
-      def assert_api_conform(status: nil, api: :default)
+      def assert_api_conform(status: nil, api: openapi_first_default_api)
         api = OpenapiFirst::Test[api]
         # :nocov:
         request = respond_to?(:last_request) ? last_request : @request

data/lib/openapi_first/test.rb

@@ -22,8 +22,8 @@ module OpenapiFirst
         yield self
       end
 
-      def register(*)
-        Test.register(*)
+      def register(oad, as: :default)
+        Test.register(oad, as:)
       end
 
       attr_accessor :minimum_coverage, :coverage_formatter_options, :coverage_formatter
@@ -47,7 +47,7 @@ module OpenapiFirst
         end
         return unless minimum_coverage > coverage
 
-        puts "API Coverage fails with exit 2, because API coverage of #{coverage}%" \
+        puts "API Coverage fails with exit 2, because API coverage of #{coverage}% " \
              "is below minimum of #{minimum_coverage}%!"
         exit 2
         # :nocov:
@@ -81,7 +81,6 @@ module OpenapiFirst
     def self.report_coverage(formatter: Coverage::TerminalFormatter, **)
       coverage_result = Coverage.result
       puts formatter.new(**).format(coverage_result)
-      puts "The overal API validation coverage of this run is: #{coverage_result.coverage}%"
     end
 
     # Returns the Rack app wrapped with silent request, response validation
@@ -104,18 +103,23 @@ module OpenapiFirst
     class << self
       attr_reader :definitions
 
-      def register(path, as: :default)
-        if definitions.key?(:default)
+      # Register an OpenAPI definition for testing
+      # @param path_or_definition [String, Definition] Path to the OpenAPI file or a Definition object
+      # @param as [Symbol] Name to register the API definition as
+      def register(path_or_definition, as: :default)
+        if definitions.key?(as) && as == :default
           raise(
             AlreadyRegisteredError,
             "#{definitions[as].filepath.inspect} is already registered " \
-            "as ':default' so you cannot register #{path.inspect} without " \
+            "as ':default' so you cannot register #{path_or_definition.inspect} without " \
             'giving it a custom name. Please call register with a custom key like: ' \
-            "OpenapiFirst::Test.register(#{path.inspect}, as: :my_other_api)"
+            "OpenapiFirst::Test.register(#{path_or_definition.inspect}, as: :my_other_api)"
           )
         end
 
-        definitions[as] = OpenapiFirst.load(path)
+        definition = OpenapiFirst.load(path_or_definition)
+        definitions[as] = definition
+        definition
       end
 
       def [](api)

data/lib/openapi_first/validators/request_parameters.rb

@@ -6,7 +6,6 @@ module OpenapiFirst
       RequestHeaders = Data.define(:schema) do
         def call(parsed_request)
           validation = schema.validate(parsed_request.headers)
-          validation = Schema::ValidationResult.new(validation.to_a)
           Failure.fail!(:invalid_header, errors: validation.errors) if validation.error?
         end
       end
@@ -14,7 +13,6 @@ module OpenapiFirst
       Path = Data.define(:schema) do
         def call(parsed_request)
           validation = schema.validate(parsed_request.path)
-          validation = Schema::ValidationResult.new(validation.to_a)
           Failure.fail!(:invalid_path, errors: validation.errors) if validation.error?
         end
       end
@@ -22,7 +20,6 @@ module OpenapiFirst
       Query = Data.define(:schema) do
         def call(parsed_request)
           validation = schema.validate(parsed_request.query)
-          validation = Schema::ValidationResult.new(validation.to_a)
           Failure.fail!(:invalid_query, errors: validation.errors) if validation.error?
         end
       end
@@ -30,7 +27,6 @@ module OpenapiFirst
       RequestCookies = Data.define(:schema) do
         def call(parsed_request)
           validation = schema.validate(parsed_request.cookies)
-          validation = Schema::ValidationResult.new(validation.to_a)
           Failure.fail!(:invalid_cookie, errors: validation.errors) if validation.error?
         end
       end
@@ -45,7 +41,7 @@ module OpenapiFirst
       def self.for(args)
         VALIDATORS.filter_map do |key, klass|
           schema = args[key]
-          klass.new(schema) if schema.value
+          klass.new(schema) if schema
         end
       end
     end

data/lib/openapi_first/validators/response_body.rb

@@ -5,13 +5,6 @@ require_relative '../schema/validation_result'
 module OpenapiFirst
   module Validators
     class ResponseBody
-      def self.for(response_definition)
-        schema = response_definition&.content_schema
-        return unless schema
-
-        new(schema)
-      end
-
       def initialize(schema)
         @schema = schema
       end

data/lib/openapi_first/validators/response_headers.rb

@@ -3,24 +3,37 @@
 module OpenapiFirst
   module Validators
     class ResponseHeaders
-      def self.for(response_definition)
-        schema = response_definition&.headers_schema
-        return unless schema&.value
-
-        new(schema)
+      def initialize(headers)
+        @headers = headers
       end
 
-      def initialize(schema)
-        @schema = schema
+      attr_reader :headers
+
+      def call(parsed_response)
+        headers.each do |header|
+          header_value = parsed_response.headers[header.name]
+          next if header_value.nil? && !header.required?
+
+          validation_errors = header.schema.validate(header_value)
+          next unless validation_errors.any?
+
+          Failure.fail!(:invalid_response_header,
+                        errors: [error_for(data_pointer: "/#{header.name}", value: header_value,
+                                           error: validation_errors.first)])
+        end
       end
 
-      attr_reader :schema
+      private
 
-      def call(parsed_request)
-        validation = Schema::ValidationResult.new(
-          schema.validate(parsed_request.headers)
+      def error_for(data_pointer:, value:, error:)
+        Schema::ValidationError.new(
+          value: value,
+          data_pointer:,
+          schema_pointer: error['schema_pointer'],
+          type: error['type'],
+          details: error['details'],
+          schema: error['schema']
         )
-        Failure.fail!(:invalid_response_header, errors: validation.errors) if validation.error?
       end
     end
   end

data/lib/openapi_first/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  VERSION = '2.5.1'
+  VERSION = '2.7.0'
 end

data/lib/openapi_first.rb

@@ -15,6 +15,10 @@ module OpenapiFirst
 
   # Key in rack to find instance of Request
   REQUEST = 'openapi.request'
+
+  # Key in rack to store the alternate path used for schema matching
+  PATH = 'openapi.path'
+
   FAILURE = :openapi_first_validation_failure
 
   # @return [Configuration]
@@ -48,9 +52,13 @@ module OpenapiFirst
     end
   end
 
-  # Load and dereference an OpenAPI spec file
+  # Load and dereference an OpenAPI spec file or return the Definition if it's already loaded
+  # @param filepath_or_definition [String, Definition] The path to the file or a Definition object
   # @return [Definition]
-  def self.load(filepath, only: nil, &)
+  def self.load(filepath_or_definition, only: nil, &)
+    return filepath_or_definition if filepath_or_definition.is_a?(Definition)
+
+    filepath = filepath_or_definition
     raise FileNotFoundError, "File not found: #{filepath}" unless File.exist?(filepath)
 
     contents = FileLoader.load(filepath)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 2.5.1
+  version: 2.7.0
 platform: ruby
 authors:
 - Andreas Haller
 bindir: bin
 cert_chain: []
-date: 2025-03-26 00:00:00.000000000 Z
+date: 2025-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hana
@@ -102,6 +102,7 @@ files:
 - lib/openapi_first/errors.rb
 - lib/openapi_first/failure.rb
 - lib/openapi_first/file_loader.rb
+- lib/openapi_first/header.rb
 - lib/openapi_first/json.rb
 - lib/openapi_first/middlewares/request_validation.rb
 - lib/openapi_first/middlewares/response_validation.rb
@@ -118,6 +119,7 @@ files:
 - lib/openapi_first/router/find_content.rb
 - lib/openapi_first/router/find_response.rb
 - lib/openapi_first/router/path_template.rb
+- lib/openapi_first/schema/hash.rb
 - lib/openapi_first/schema/validation_error.rb
 - lib/openapi_first/schema/validation_result.rb
 - lib/openapi_first/test.rb