openapi_first 2.11.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c84ae6fc48433fbbe1845ff66ed2315b58a47ff3ba17ea6756bb6c276db5ed3
-  data.tar.gz: 3b584da97ce9b7ea712dc66ac55e39a16c1631254dd719551d27a4df9bc13e4c
+  metadata.gz: 7474086c282336d7e77afe8143a0bda6e0a4a36fe284a746804bd933bdfd45a6
+  data.tar.gz: 7538b4bd0e9f30f3d95c5cb06842b03e15644ce441018577c467629ce62d9772
 SHA512:
-  metadata.gz: 863d5ea4124958e81d62e7a72efef17e6fe5326fe4db6d34bc6fe97e8ec863c09dd8d138eaf9b249ce94ce490dad937297cd9d15b98dc73a6c01f30c6f6da2f7
-  data.tar.gz: 7c5c264ce6f969788986bbaf71cb6060b998ae5819cf5551ddf4f82ab2069c87afda22e97fa9c8aa03ea91bb6133cbf579d63b35a12c0eb30a7e17a774508ec7
+  metadata.gz: 2d1469a59f294ce4b386fb60da3e7c019773a8516005d1b3c0f60bd26158e62a879367647cab558579085a3b3c866055ac70b3df255c2fb38d7d918e10892154
+  data.tar.gz: 835f24859d1510dfbe6a3fa99f1d9a496a0011441b041f8d92ee884b5938d53b5550fbe336a36adf44e6f8711fc30ec5333a7310de65cc93da8402e107b6beb4

data/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## Unreleased
 
+## 3.0.0
+
+### openapi_first
+
+#### Changed
+- Breaking: Trailing slashes are no longer ignored in dynamic paths. See [#403](https://github.com/ahx/openapi_first/issues/403).
+  Before this change `GET /things/24/` matched `/things/{id}:`, but it no longer does.
+- Breaking: Failure type `:response_not_found` was split into two more specific types `:response_content_type_not_found` and `:response_status_not_found`. This should be mostly internal stuff. So if your custom error response used `response_not_found`, you will have to adapt.
+- Deprecated configuration fields `request_validation_raise_error` and `response_validation_raise_error`. Please pass the `raise_error:` option to the middlewares directly.
+
+#### Added
+- Added support to register OADs globally via:
+  ```ruby
+  OpenapiFirst.configure { |config| config.register('openapi.yaml')  }
+  ```
+  This makes the `spec` argument in middlewares optional and removes the necessity to load the OAD in the same place where you use the middlewares and adds a cache for parsed OADs.
+
+#### Removed
+- Removed deprecated methods which produced a warning since 2.0.0.
+- Removed `OpenapiFirst::Configuration#clone`. Use `#child` instead.
+- It's no longer supported to remove locally added hooks during runtime.
+
+#### Fixed
+- Update dependency `openapi_parameters` to >= 0.7.0, because that version supports unpacking parameters the use `style: deepObject` with `explode: true`.
+- Make `OpenapiFirst::Test.setup` more robust by adding `OpenapiFirst::Configuration#child` so it does not matter if you load our OAD before callig `OpenapiFirst::Test.setup`.
+
+### openapi_first/test
+
+#### Changed
+- `OpenapiFirst::Test.app` now returns an instance of `OpenapiFirst::Test::App`, instead of `Rack::Builer` and delegates methods other than `#call` to the original app. This wrapper adds validated requests, responses to the rack env at `env[OpenapiFirst::Test::REQUEST]`, `env[OpenapiFirst::Test::RESPONSE]`. This makes it possible to test Rails engines. Thanks to Josh! See [#410](https://github.com/ahx/openapi_first/issues/410).
+- `OpenapiFirst::Test` now falls back to using globally registered OADs if nothing was registered inside `OpenapiFirst::Test.setup`.
+- 401er and 500er status are okay to not be described.
+
+#### Added
+- The Coverage feature in `OpenapiFirst::Test` now supports parallel tests via a DRB client/sever. Thanks to Richard! See [#394](https://github.com/ahx/openapi_first/issues/394).
+- Added `OpenapiFirst::Test` Configuration options which are useful when adopting OpenAPI:
+  - `ignore_unknown_response_status = true` to make API coverage no longer complain about undefined response statuses it sees during a test run.
+  - `minimum_coverage=` is no longer deprecated. This is useful when gradually adopting OpenAPI
+- `ignored_unknown_status=` to overwrite the whole list of ignored unknown status at once
+
+#### Removed
+- Removed internally used `Test::Coverage.current_run, .plans, .install, .uninstall`. If you are using these, use `OpenapiFirst::Test.setup` instead.
+
+#### Fixed
+- Make `OpenapiFirst::Test.setup` more robust by adding `OpenapiFirst::Configuration#child` so it does not matter if you load our OAD before callig `OpenapiFirst::Test.setup`.
+
 ## 2.11.1
 
 - OpenapiFirst can now route requests correctly for paths like `/stuffs` and `/stuffs{format}` (https://github.com/ahx/openapi_first/issues/386)

data/README.md

@@ -4,18 +4,21 @@ openapi_first is a Ruby gem for request / response validation and contract-testi
 
 ## Usage
 
+Configure
+```ruby
+OpenapiFirst.register('openapi/openapi.yaml')
+```
+
 Use an OAD to validate incoming requests:
 ```ruby
-use OpenapiFirst::Middlewares::RequestValidation, 'openapi/openapi.yaml'
+use OpenapiFirst::Middlewares::RequestValidation
 ```
 
 Turn your request tests into [contract tests](#contract-testing) against an OAD:
 ```ruby
 # spec_helper.rb
 require 'openapi_first'
-OpenapiFirst::Test.setup do |config|
-  config.register('openapi/openapi.yaml')
-end
+OpenapiFirst::Test.setup
 
 require 'my_app'
 RSpec.configure do |config|
@@ -27,6 +30,7 @@ end
 
 <!-- TOC -->
 
+- [Configuration](#configuration)
 - [Rack Middlewares](#rack-middlewares)
   - [Request validation](#request-validation)
   - [Response validation](#response-validation)
@@ -34,7 +38,6 @@ end
   - [Test assertions](#test-assertions)
 - [Manual use](#manual-use)
 - [Framework integration](#framework-integration)
-- [Configuration](#configuration)
 - [Hooks](#hooks)
 - [Alternatives](#alternatives)
 - [Frequently Asked Questions](#frequently-asked-questions)
@@ -44,6 +47,33 @@ end
 
 <!-- /TOC -->
 
+## 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).
+```ruby
+OpenapiFirst.configure do |config|
+  config.register('openapi/openapi.yaml') # :default
+  config.register('openapi/v1.openapi.yaml', as: :v1)
+end
+```
+
+You can configure default options globally:
+
+```ruby
+OpenapiFirst.configure do |config|
+  # Specify which plugin is used to render error responses returned by the request validation middleware (defaults to :default)
+  config.request_validation_error_response = :jsonapi
+end
+```
+
+or configure per instance:
+
+```ruby
+OpenapiFirst.load('openapi.yaml') do |config|
+  config.request_validation_error_response = :jsonapi
+end
+```
+
 ## Rack Middlewares
 
 ### Request validation
@@ -51,10 +81,10 @@ end
 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, 'openapi.yaml'
+use OpenapiFirst::Middlewares::RequestValidation
 
 # Pass `raise_error: true` to raise an error if request is invalid:
-use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml', raise_error: true
+use OpenapiFirst::Middlewares::RequestValidation, raise_error: true
 ```
 
 #### Error responses
@@ -92,7 +122,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, 'openapi.yaml', error_response: :jsonapi
 ```
 
 <details>
@@ -145,10 +175,10 @@ 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, 'openapi.yaml' if ENV['RACK_ENV'] == 'test'
+use OpenapiFirst::Middlewares::ResponseValidation if ENV['RACK_ENV'] == 'test'
 
 # Pass `raise_error: false` to not raise an error:
-use OpenapiFirst::Middlewares::ResponseValidation, 'openapi.yaml', raise_error: false
+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.
@@ -159,13 +189,11 @@ You can see your OpenAPI API description as a contract that your clients can rel
 
 Here is how to set it up:
 
-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.
+1. Setup the test mode
     ```ruby
+    # spec_helper.rb
     require 'openapi_first'
-    OpenapiFirst::Test.setup do |config|
-      config.register('openapi/openapi.yaml')
-    end
+    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.
@@ -188,7 +216,7 @@ Here is how to set it up:
         config.include OpenapiFirst::Test::Methods[MyApp], type: :request
       end
       ```
-4. Run your tests. The Coverage feature will tell you about missing or invalid requests/responses:
+3. Run your tests. The Coverage feature will tell you about missing or invalid requests/responses:
       ```
       ✓ GET /stations
         ✓ 200(application/json)
@@ -203,11 +231,19 @@ Here is how to set it up:
 
 ### Configure test coverage
 
-OpenapiFirst::Test raises an error when a response status is not defined. You can deactivate this with:
+OpenapiFirst::Test raises an error when a response status is not defined except for 404 and 500. You can change this:
 
 ```ruby
 OpenapiFirst::Test.setup do |test|
-  [403, 401].each { test.ignored_unknown_status << it }
+  test.ignored_unknown_status << 403
+end
+```
+
+Or you can ignore all unknown response status:
+
+```ruby
+OpenapiFirst::Test.setup do |test|
+  test.ignore_all_unknown_status = true
 end
 ```
 
@@ -215,7 +251,6 @@ Exclude certain _responses_ from coverage with `skip_coverage`:
 
 ```ruby
 OpenapiFirst::Test.setup do |test|
-  # …
   test.skip_response_coverage do |response_definition|
     response_definition.status == '5XX'
   end
@@ -226,7 +261,6 @@ 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'
   end
@@ -237,32 +271,36 @@ OpenapiFirst::Test raises an error when a request is not defined. You can deacti
 
 ```ruby
 OpenapiFirst::Test.setup do |test|
-  # …
   test.ignore_unknown_requests = true
 end
 ```
 
 ### Test assertions
 
-openapi_first ships with a simple but powerful Test method to run request and response validation in your tests without using the middlewares. This is designed to be used with rack-test or Ruby on Rails integration tests or request specs.
+> [!WARNING]
+> You probably don't need this. Just setup [Contract testing and API coverage](#contract-testing) and use your normal assertions.
 
-Here is how to set it up for Rails integration tests:
+openapi_first ships with a simple but powerful Test method `assert_api_conform` to run request and response validation in your tests without using the middlewares. This is designed to be used with rack-test.
+
+Here is how to use it with RSpec, but MiniTest works just as good:
 
-Inside your test:
 ```ruby
-# test/integration/trips_api_test.rb
-require 'test_helper'
+# spec_helper.rb
+OpenapiFirst::Test.setup do |test|
+  test.register(File.join(__dir__, '../examples/openapi.yaml'), as: :example_app)
+end
+```
 
-class TripsApiTest < ActionDispatch::IntegrationTest
-  include OpenapiFirst::Test::Methods
 
-  test 'GET /trips' do
-    get '/trips',
-        params: { origin: 'efdbb9d1-02c2-4bc3-afb7-6788d8782b1e', destination: 'b2e783e1-c824-4d63-b37a-d8d698862f1d',
-                  date: '2024-07-02T09:00:00Z' }
+Inside your test :
+```ruby
+RSpec.describe 'Example App' do
+  include Rack::Test::Methods
+  include OpenapiFirst::Test::Methods[App]
 
+  it 'is API conform' do
+    get '/'
     assert_api_conform(status: 200)
-    # assert_api_conform(status: 200, api: :v1) # Or this if you have multiple API descriptions
   end
 end
 ```
@@ -320,27 +358,6 @@ validated_response.parsed_headers
 definition.validate_response(rack_request,rack_response, raise_error: true) # Raises OpenapiFirst::ResponseInvalidError or OpenapiFirst::ResponseNotFoundError
 ```
 
-## Configuration
-
-You can configure default options globally:
-
-```ruby
-OpenapiFirst.configure do |config|
-  # Specify which plugin is used to render error responses returned by the request validation middleware (defaults to :default)
-  config.request_validation_error_response = :jsonapi
-  # Configure if the request validation middleware should raise an exception (defaults to false)
-  config.request_validation_raise_error = true
-end
-```
-
-or configure per instance:
-
-```ruby
-OpenapiFirst.load('openapi.yaml') do |config|
-  config.request_validation_error_response = :jsonapi
-end
-```
-
 ## Hooks
 
 You can integrate your code at certain points during request/response validation via hooks.
@@ -380,11 +397,10 @@ end
 ## Framework integration
 
 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).
+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).
 
 ## Alternatives
 

data/lib/openapi_first/builder.rb

@@ -125,7 +125,7 @@ module OpenapiFirst
       end
 
       Schema::Hash.new(schemas, required:, configuration: schemer_configuration,
-                                after_property_validation: config.hooks[:after_request_parameter_property_validation])
+                                after_property_validation: config.after_request_parameter_property_validation)
     end
 
     def build_requests(path:, request_method:, operation_object:, parameters:)
@@ -139,7 +139,7 @@ module OpenapiFirst
       content_objects.map do |content_type, content_object|
         content_schema = content_object['schema'].schema(
           configuration: schemer_configuration,
-          after_property_validation: config.hooks[:after_request_body_property_validation]
+          after_property_validation: config.after_request_body_property_validation
         )
         Request.new(path:, request_method:, parameters:,
                     operation_object: operation_object.resolved,

data/lib/openapi_first/child_configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # A subclass to configuration that points to its parent
+  class ChildConfiguration < Configuration
+    def initialize(parent:)
+      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
+
+    private attr_reader :parent
+
+    HOOKS.each do |hook|
+      define_method(hook) do |&block|
+        return hooks[hook].chain(parent.hooks[hook]) if block.nil?
+
+        hooks[hook] << block
+        block
+      end
+    end
+  end
+end

data/lib/openapi_first/configuration.rb

@@ -18,17 +18,48 @@ module OpenapiFirst
       @path = nil
     end
 
-    attr_reader :request_validation_error_response, :hooks
-    attr_accessor :request_validation_raise_error, :response_validation_raise_error, :path
+    def register(path_or_definition, as: :default)
+      OpenapiFirst.register(path_or_definition, as:)
+    end
+
+    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)
+    end
 
+    # @visibility private
     def clone
-      copy = super
-      copy.instance_variable_set(:@hooks, @hooks&.transform_values(&:clone))
-      copy
+      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?
+
         hooks[hook] << block
         block
       end

data/lib/openapi_first/definition.rb

@@ -22,7 +22,7 @@ module OpenapiFirst
     # @param filepath [String] The file path of the OpenAPI document.
     def initialize(contents, filepath = nil)
       @filepath = filepath
-      @config = OpenapiFirst.configuration.clone
+      @config = OpenapiFirst.configuration.child
       yield @config if block_given?
       @config.freeze
       @router = Builder.build_router(contents, filepath:, config:)
@@ -58,6 +58,10 @@ module OpenapiFirst
       "#{title} @ #{version}"
     end
 
+    def inspect
+      "#<#{self.class.name} @key='#{key}'>"
+    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.
@@ -69,7 +73,7 @@ module OpenapiFirst
       else
         route.request_definition.validate(request, route_params: route.params)
       end.tap do |validated|
-        @config.hooks[:after_request_validation].each { |hook| hook.call(validated, self) }
+        @config.after_request_validation.each { |hook| hook.call(validated, self) }
         raise validated.error.exception(validated) if validated.error && raise_error
       end
     end
@@ -91,7 +95,7 @@ module OpenapiFirst
                   else
                     response_match.response.validate(rack_response)
                   end
-      @config.hooks[:after_response_validation]&.each { |hook| hook.call(validated, rack_request, self) }
+      @config.after_response_validation&.each { |hook| hook.call(validated, rack_request, self) }
       raise validated.error.exception(validated) if raise_error && validated.invalid?
 
       validated

data/lib/openapi_first/failure.rb

@@ -13,7 +13,8 @@ module OpenapiFirst
       invalid_header: [RequestInvalidError, 'Request header is invalid:'],
       invalid_path: [RequestInvalidError, 'Path segment is invalid:'],
       invalid_cookie: [RequestInvalidError, 'Cookie value is invalid:'],
-      response_not_found: [ResponseNotFoundError],
+      response_content_type_not_found: [ResponseNotFoundError],
+      response_status_not_found: [ResponseNotFoundError],
       invalid_response_body: [ResponseInvalidError, 'Response body is invalid:'],
       invalid_response_header: [ResponseInvalidError, 'Response header is invalid:']
     }.freeze
@@ -65,12 +66,6 @@ module OpenapiFirst
       [message_prefix, @message || generate_message].compact.join(' ')
     end
 
-    # @deprecated Please use {#type} instead
-    def error_type
-      warn 'OpenapiFirst::Failure#error_type is deprecated. Use #type instead.'
-      type
-    end
-
     private
 
     def generate_message

data/lib/openapi_first/middlewares/request_validation.rb

@@ -6,9 +6,11 @@ module OpenapiFirst
     # A Rack middleware to validate requests against an OpenAPI API description
     class RequestValidation
       # @param app The parent Rack application
-      # @param spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      # @param spec [String, Symbol, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #   If you pass a Symbol, it will load the OAD registered via `OpenapiFirst.register`
+      #   If you leave this blank, it will load the OAD registered as `:default`
       # @param options Hash
-      #   :spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #   :spec [String, Symbol, 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
@@ -20,13 +22,13 @@ module OpenapiFirst
         @app = app
         if spec.is_a?(Hash)
           options = spec
-          spec = options.fetch(:spec)
+          spec = options[: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)
-        raise "You have to pass spec: when initializing #{self.class}" unless spec
+        spec ||= :default
+        spec = OpenapiFirst[spec] if spec.is_a?(Symbol)
 
         @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)
       end

data/lib/openapi_first/middlewares/response_validation.rb

@@ -6,7 +6,9 @@ module OpenapiFirst
   module Middlewares
     # A Rack middleware to validate requests against an OpenAPI API description
     class ResponseValidation
-      # @param spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition
+      # @param spec [String, Symbol, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #   If you pass a Symbol, it will load the OAD registered via `OpenapiFirst.register`
+      #   If you leave this blank, it will load the OAD registered as `:default`
       # @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.
@@ -15,11 +17,12 @@ module OpenapiFirst
         @app = app
         if spec.is_a?(Hash)
           options = spec
-          spec = options.fetch(:spec)
+          spec = options[:spec]
         end
         @raise = options.fetch(:raise_error, OpenapiFirst.configuration.response_validation_raise_error)
 
-        raise "You have to pass spec: when initializing #{self.class}" unless spec
+        spec ||= :default
+        spec = OpenapiFirst[spec] if spec.is_a?(Symbol)
 
         @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)
       end

data/lib/openapi_first/registry.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class NotRegisteredError < Error; end
+  class AlreadyRegisteredError < Error; end
+
+  # @visibility private
+  module Registry
+    def definitions
+      @definitions ||= {}
+    end
+
+    # 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].inspect} is already registered " \
+          "as ':default' so you cannot register #{path_or_definition.inspect} without " \
+          'giving it a custom name. Please call register with a custom key like: ' \
+          "#{name}.register(#{path_or_definition.inspect}, as: :my_other_api)"
+        )
+      end
+
+      definition = OpenapiFirst.load(path_or_definition)
+      definitions[as] = definition
+      definition
+    end
+
+    def [](api)
+      return api if api.is_a?(Definition)
+
+      definitions.fetch(api) do
+        option = api == :default ? '' : ", as: #{api.inspect}"
+        raise(NotRegisteredError,
+              "API description '#{api.inspect}' not found." \
+              "Please call #{name}.register('myopenapi.yaml'#{option}) " \
+              'once before running your app.')
+      end
+    end
+  end
+end

data/lib/openapi_first/router/find_response.rb

@@ -10,18 +10,15 @@ module OpenapiFirst
 
       def self.call(responses, status, content_type, request_method:, path:)
         contents = find_status(responses, status)
-        if contents.nil?
-          message = "Status #{status} is not defined for #{request_method.upcase} #{path}. " \
-                    "Defined statuses are: #{responses.keys.join(', ')}."
-          return Match.new(error: Failure.new(:response_not_found, message:), response: nil)
-        end
+        return response_status_not_found(status:, request_method:, path:, responses:) if contents.nil?
+
         response = FindContent.call(contents, content_type)
-        return response_not_found(content_type:, contents:, request_method:, path:) unless response
+        return response_content_type_not_found(content_type:, contents:, request_method:, path:) unless response
 
         Match.new(response:, error: nil)
       end
 
-      def self.response_not_found(content_type:, contents:, request_method:, path:)
+      def self.response_content_type_not_found(content_type:, contents:, request_method:, path:)
         empty_content = content_type.nil? || content_type.empty?
         message =
           "Content-Type should be #{contents.keys.join(' or ')}, " \
@@ -29,11 +26,18 @@ module OpenapiFirst
           "#{request_method.upcase} #{path}"
 
         Match.new(
-          error: Failure.new(:response_not_found, message:),
+          error: Failure.new(:response_content_type_not_found, message:),
           response: nil
         )
       end
-      private_class_method :response_not_found
+      private_class_method :response_content_type_not_found
+
+      def self.response_status_not_found(status:, request_method:, path:, responses:)
+        message = "Status #{status} is not defined for #{request_method.upcase} #{path}. " \
+                  "Defined statuses are: #{responses.keys.join(', ')}."
+        Match.new(error: Failure.new(:response_status_not_found, message:), response: nil)
+      end
+      private_class_method :response_status_not_found
 
       def self.find_status(responses, status)
         # According to OAS status has to be a string,

data/lib/openapi_first/router/path_template.rb

@@ -41,7 +41,7 @@ module OpenapiFirst
           part.start_with?('{') ? ALLOWED_PARAMETER_CHARACTERS : Regexp.escape(part)
         end
 
-        %r{^#{parts.join}/?$}
+        /^#{parts.join}$/
       end
     end
   end

data/lib/openapi_first/schema/validation_error.rb

@@ -40,24 +40,6 @@ module OpenapiFirst
           "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.'
-        message
-      end
-
-      # @deprecated Please use {#data_pointer} instead
-      def instance_location
-        warn 'OpenapiFirst::Schema::ValidationError#instance_location is deprecated. Use #data_pointer instead.'
-        data_pointer
-      end
-
-      # @deprecated Please use {#schema_pointer} instead
-      def schema_location
-        warn 'OpenapiFirst::Schema::ValidationError#schema_location is deprecated. Use #schema_pointer instead.'
-        schema_pointer
-      end
     end
   end
 end

data/lib/openapi_first/test/app.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'observe'
+
+module OpenapiFirst
+  module Test
+    REQUEST = 'openapi.test.request'
+    RESPONSE = 'openapi.test.response'
+
+    # A wrapper of the original app
+    # with silent request/response validation to track requests/responses.
+    class App < SimpleDelegator
+      def initialize(app, api:)
+        super(app)
+        @app = app
+        @definition = Test[api]
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        env[Test::REQUEST] = @definition.validate_request(request, raise_error: false)
+        response = @app.call(env)
+        status, headers, body = response
+        env[Test::RESPONSE] =
+          @definition.validate_response(request, Rack::Response[status, headers, body], raise_error: false)
+        response
+      end
+    end
+  end
+end

data/lib/openapi_first/test/callable.rb

@@ -6,7 +6,7 @@ module OpenapiFirst
     # This is used by Openapi::Test.observe
     module Callable
       # Returns a Module with a `call(env)` method that wraps super inside silent request/response validation
-      # You can use this like `Application.prepend(OpenapiFirst::Test.app_module)` to monitor your app during testing.
+      # You can use `Application.prepend(OpenapiFirst::Test::Callable[oad])` to monitor your app during testing.
       def self.[](definition)
         Module.new.tap do |mod|
           mod.define_method(:call) do |env|

data/lib/openapi_first/test/configuration.rb

@@ -11,28 +11,33 @@ module OpenapiFirst
         @skip_response_coverage = nil
         @skip_coverage = nil
         @response_raise_error = true
-        @ignored_unknown_status = [404]
+        @ignored_unknown_status = Set.new([401, 404, 500])
+        @ignore_unknown_response_status = false
         @report_coverage = true
         @ignore_unknown_requests = false
-        @registry = {}
-        @apps = {}
       end
 
       # Register OADs, but don't load them just yet
       # @param [OpenapiFirst::OAD] oad The OAD to register
       # @param [Symbol] as The name to register the OAD under
       def register(oad, as: :default)
-        @registry[as] = oad
+        Test.register(oad, as:)
       end
 
       # Observe a rack app
       def observe(app, api: :default)
-        (@apps[api] ||= []) << app
+        Observe.observe(app, api:)
       end
 
       attr_accessor :coverage_formatter_options, :coverage_formatter, :response_raise_error,
-                    :ignore_unknown_requests
-      attr_reader :registry, :apps, :report_coverage, :ignored_unknown_status, :minimum_coverage
+                    :ignore_unknown_requests, :ignore_unknown_response_status, :minimum_coverage
+      attr_reader :report_coverage, :ignored_unknown_status
+
+      # Set ignored unknown status codes.
+      # @param [Array<Integer>] status Status codes that are okay not to cover in an OAD
+      def ignored_unknown_status=(status)
+        @ignored_unknown_status = status.to_set
+      end
 
       # Configure report coverage
       # @param [Boolean, :warn] value Whether to report coverage or just warn.
@@ -45,13 +50,6 @@ module OpenapiFirst
         @report_coverage = value
       end
 
-      # @deprecated Use skip_response_coverage, ignored_unknown_status or skip_coverage to configure coverage
-      def minimum_coverage=(value)
-        warn 'OpenapiFirst::Test::Configuration#minimum_coverage= is deprecated. ' \
-             'Use skip_response_coverage, ignored_unknown_status to configure coverage instead.'
-        @minimum_coverage = value
-      end
-
       def skip_response_coverage(&block)
         return @skip_response_coverage unless block_given?
 
@@ -63,6 +61,16 @@ module OpenapiFirst
 
         @skip_coverage = block
       end
+
+      alias ignore_unknown_response_status? ignore_unknown_response_status
+
+      def ignore_response?(validated_response)
+        return false if validated_response.known?
+
+        return true if ignored_unknown_status.include?(validated_response.status)
+
+        ignore_unknown_response_status? && validated_response.error.type == :response_status_not_found
+      end
     end
   end
 end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      CoveredRequest = Data.define(:key, :error) do
+        def valid? = error.nil?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      CoveredResponse = Data.define(:key, :error) do
+        def valid? = error.nil?
+      end
+    end
+  end
+end

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

@@ -37,11 +37,11 @@ module OpenapiFirst
         private attr_reader :index
 
         def track_request(validated_request)
-          index[validated_request.request_definition.key]&.track(validated_request) if validated_request.known?
+          index[validated_request.key]&.track(validated_request)
         end
 
         def track_response(validated_response)
-          index[validated_response.response_definition.key]&.track(validated_response) if validated_response.known?
+          index[validated_response.key]&.track(validated_response)
         end
 
         def done?

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # Class that allows tracking requests and response for OAD definitions.
+      # For each definition it builds a plan and forwards tracking to the correct plan.
+      class Tracker
+        attr_reader :plans_by_key
+
+        def initialize(definitions, skip_response: nil, skip_route: nil)
+          @plans_by_key = definitions.values.to_h do |oad|
+            plan = Plan.for(oad, skip_response:, skip_route:)
+            [oad.key, plan]
+          end
+        end
+
+        def track_request(key, request)
+          @plans_by_key[key]&.track_request(request)
+        end
+
+        def track_response(key, response)
+          @plans_by_key[key]&.track_response(response)
+        end
+
+        def plans
+          @plans_by_key.values
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/test/coverage.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require_relative 'coverage/plan'
+require_relative 'coverage/tracker'
+require_relative 'coverage/covered_request'
+require_relative 'coverage/covered_response'
+require 'drb'
 
 module OpenapiFirst
   module Test
@@ -12,45 +16,80 @@ module OpenapiFirst
 
       Result = Data.define(:plans, :coverage)
 
-      @current_run = {}
-
       class << self
-        attr_reader :current_run
+        def start(skip_response: nil, skip_route: nil)
+          return if @drb_uri
 
-        def install = Test.install
+          tracker = Tracker.new(Test.definitions, skip_response:, skip_route:)
 
-        def start(skip_response: nil, skip_route: nil)
-          @current_run = Test.definitions.values.to_h do |oad|
-            plan = Plan.for(oad, skip_response:, skip_route:)
-            [oad.key, plan]
-          end
+          # We need a custom DRbServer (not using DRb.start_service) because otherwise
+          # we'd conflict with Rails's DRb server
+          @drb_uri = DRb::DRbServer.new(nil, tracker).uri
         end
 
-        def uninstall = Test.uninstall
-
         # Clear current coverage run
         def reset
-          @current_run = {}
+          @tracker = nil
+
+          return unless @drb_uri
+
+          service = DRb.fetch_server(@drb_uri)
+          service&.stop_service
+          @drb_uri = nil
         end
 
         def track_request(request, oad)
-          current_run[oad.key]&.track_request(request)
+          return unless request.known?
+
+          # The call to `track_request` may happen remotely in the main process that started
+          # the coverage collection.
+          # To make this work we need to keep arguments trivial, which is the reason the request
+          # is wrapped in a CoveredRequest data object.
+          tracker&.track_request(
+            oad.key,
+            CoveredRequest.new(
+              key: request.request_definition.key,
+              error: request.error
+            )
+          )
         end
 
         def track_response(response, _request, oad)
-          current_run[oad.key]&.track_response(response)
+          return unless response.known?
+
+          # The call to `track_response` may happen remotely in the main process that started
+          # the coverage collection.
+          # To make this work we need to keep arguments trivial, which is the reason the response
+          # is wrapped in a CoveredResponse data object.
+          tracker&.track_response(
+            oad.key,
+            CoveredResponse.new(
+              key: response.response_definition.key,
+              error: response.error
+            )
+          )
         end
 
         def result
           Result.new(plans:, coverage:)
         end
 
+        private
+
+        def current_run
+          tracker.plans_by_key
+        end
+
         # Returns all plans (Plan) that were registered for this run
         def plans
-          current_run.values
+          tracker&.plans || []
         end
 
-        private
+        def tracker
+          return unless @drb_uri
+
+          @tracker ||= DRbObject.new_with_uri(@drb_uri)
+        end
 
         def coverage
           return 0 if plans.empty?

data/lib/openapi_first/test/observe.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'callable'
+
 module OpenapiFirst
   module Test
     class ObserveError < Error; end

data/lib/openapi_first/test.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 require_relative 'test/configuration'
-require_relative 'test/registry'
+require_relative 'registry'
 
 module OpenapiFirst
   # Test integration
   module Test
     autoload :Coverage, 'openapi_first/test/coverage'
     autoload :Methods, 'openapi_first/test/methods'
-    autoload :Callable, 'openapi_first/test/callable'
     autoload :Observe, 'openapi_first/test/observe'
+    autoload :App, 'openapi_first/test/app'
     extend Registry
 
     class CoverageError < Error; end
@@ -25,6 +25,10 @@ module OpenapiFirst
       false
     end
 
+    def self.definitions
+      super.empty? ? OpenapiFirst.definitions : super
+    end
+
     def self.configuration
       @configuration ||= Configuration.new
     end
@@ -32,29 +36,28 @@ module OpenapiFirst
     # Sets up OpenAPI test coverage and OAD registration.
     # @yieldparam [OpenapiFirst::Test::Configuration] configuration A configuration to setup test integration
     def self.setup
-      unless block_given?
-        raise ArgumentError, "Please provide a block to #{self.class}.confgure to register you API descriptions"
-      end
-
       install
-      yield configuration
+      yield configuration if block_given?
 
-      configuration.registry.each { |name, oad| register(oad, as: name) }
-      configuration.apps.each { |name, apps| apps.each { |app| observe(app, api: name) } }
       Coverage.start(skip_response: configuration.skip_response_coverage, skip_route: configuration.skip_coverage)
 
       if definitions.empty?
         raise NotRegisteredError,
               'No API descriptions have been registered. ' \
               'Please register your API description via ' \
-              "OpenapiFirst::Test.setup { |test| test.register('myopenapi.yaml') }"
+              "`OpenapiFirst.register('myopenapi.yaml)` or " \
+              'in a block passed to `OpenapiFirst::Test.setup` like this: ' \
+              "`OpenapiFirst::Test.setup { |test| test.register('myopenapi.yaml') }` " \
+
       end
 
       @exit_handler = method(:handle_exit)
 
+      main_process = Process.pid
       @setup ||= at_exit do
         # :nocov:
-        @exit_handler&.call
+        # Only handle exit once in the main process
+        @exit_handler&.call if Process.pid == main_process
         # :nocov:
       end
     end
@@ -88,11 +91,7 @@ module OpenapiFirst
     # the middlewares or manual request, response validation.
     def self.app(app, spec: nil, api: :default)
       spec ||= self[api]
-      Rack::Builder.app do
-        use OpenapiFirst::Middlewares::ResponseValidation, spec:, raise_error: false
-        use OpenapiFirst::Middlewares::RequestValidation, spec:, raise_error: false, error_response: false
-        run app
-      end
+      App.new(app, api: spec)
     end
 
     def self.install
@@ -123,14 +122,14 @@ module OpenapiFirst
       !configuration.ignore_unknown_requests
     end
 
-    def self.raise_response_error?(validated_response)
-      configuration.response_raise_error && !configuration.ignored_unknown_status.include?(validated_response.status)
+    def self.raise_response_error?(invalid_response)
+      configuration.response_raise_error && !configuration.ignore_response?(invalid_response)
     end
 
     def self.uninstall
       configuration = OpenapiFirst.configuration
-      configuration.hooks[:after_request_validation].delete(@after_request_validation)
-      configuration.hooks[:after_response_validation].delete(@after_response_validation)
+      configuration.after_request_validation.delete(@after_request_validation)
+      configuration.after_response_validation.delete(@after_response_validation)
       definitions.clear
       @configuration = nil
       @installed = nil

data/lib/openapi_first/validated_response.rb

@@ -24,14 +24,16 @@ module OpenapiFirst
     attr_reader :response_definition
 
     # The parsed headers
-    # @!method parsed_headers
-    # @return [Hash<String,anything>]
-    def_delegator :@parsed_values, :headers, :parsed_headers
+    # @return [Hash<String,anything>, nil]
+    def parsed_headers
+      @parsed_values&.headers
+    end
 
     # The parsed body
-    # @!method parsed_body
-    # @return [Hash<String,anything>]
-    def_delegator :@parsed_values, :body, :parsed_body
+    # @return [Hash<String,anything>, nil]
+    def parsed_body
+      @parsed_values&.body
+    end
 
     # Checks if the response is valid.
     # @return [Boolean] true if the response is valid, false otherwise.

data/lib/openapi_first/version.rb

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

data/lib/openapi_first.rb

@@ -3,7 +3,9 @@
 require_relative 'openapi_first/json'
 require_relative 'openapi_first/file_loader'
 require_relative 'openapi_first/errors'
+require_relative 'openapi_first/registry'
 require_relative 'openapi_first/configuration'
+require_relative 'openapi_first/child_configuration'
 require_relative 'openapi_first/definition'
 require_relative 'openapi_first/version'
 require_relative 'openapi_first/middlewares/response_validation'
@@ -11,6 +13,8 @@ require_relative 'openapi_first/middlewares/request_validation'
 
 # OpenapiFirst is a toolchain to build HTTP APIS based on OpenAPI API descriptions.
 module OpenapiFirst
+  extend Registry
+
   autoload :Test, 'openapi_first/test'
 
   # Key in rack to find instance of Request
@@ -26,7 +30,7 @@ module OpenapiFirst
   # @return [Configuration]
   # @yield [Configuration]
   def self.configure
-    yield configuration
+    yield configuration if block_given?
   end
 
   ERROR_RESPONSES = {} # rubocop:disable Style/MutableConstant
@@ -54,6 +58,7 @@ module OpenapiFirst
   # @return [Definition]
   def self.load(filepath_or_definition, only: nil, &)
     return filepath_or_definition if filepath_or_definition.is_a?(Definition)
+    return self[filepath_or_definition] if filepath_or_definition.is_a?(Symbol)
 
     filepath = filepath_or_definition
     raise FileNotFoundError, "File not found: #{filepath}" unless File.exist?(filepath)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 2.11.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Andreas Haller
@@ -49,7 +49,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.7.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -59,7 +59,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.7.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -94,6 +94,7 @@ files:
 - README.md
 - lib/openapi_first.rb
 - lib/openapi_first/builder.rb
+- lib/openapi_first/child_configuration.rb
 - lib/openapi_first/configuration.rb
 - lib/openapi_first/definition.rb
 - lib/openapi_first/error_response.rb
@@ -107,6 +108,7 @@ files:
 - lib/openapi_first/middlewares/request_validation.rb
 - lib/openapi_first/middlewares/response_validation.rb
 - lib/openapi_first/ref_resolver.rb
+- lib/openapi_first/registry.rb
 - lib/openapi_first/request.rb
 - lib/openapi_first/request_body_parsers.rb
 - lib/openapi_first/request_parser.rb
@@ -123,20 +125,23 @@ files:
 - lib/openapi_first/schema/validation_error.rb
 - lib/openapi_first/schema/validation_result.rb
 - lib/openapi_first/test.rb
+- lib/openapi_first/test/app.rb
 - lib/openapi_first/test/callable.rb
 - lib/openapi_first/test/configuration.rb
 - lib/openapi_first/test/coverage.rb
+- lib/openapi_first/test/coverage/covered_request.rb
+- lib/openapi_first/test/coverage/covered_response.rb
 - lib/openapi_first/test/coverage/plan.rb
 - lib/openapi_first/test/coverage/request_task.rb
 - lib/openapi_first/test/coverage/response_task.rb
 - lib/openapi_first/test/coverage/route_task.rb
 - lib/openapi_first/test/coverage/terminal_formatter.rb
+- lib/openapi_first/test/coverage/tracker.rb
 - lib/openapi_first/test/methods.rb
 - lib/openapi_first/test/minitest_helpers.rb
 - lib/openapi_first/test/observe.rb
 - lib/openapi_first/test/observer_middleware.rb
 - lib/openapi_first/test/plain_helpers.rb
-- lib/openapi_first/test/registry.rb
 - lib/openapi_first/validated_request.rb
 - lib/openapi_first/validated_response.rb
 - lib/openapi_first/validators/request_body.rb

data/lib/openapi_first/test/registry.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module OpenapiFirst
-  module Test
-    class NotRegisteredError < Error; end
-    class AlreadyRegisteredError < Error; end
-
-    # @visibility private
-    module Registry
-      def definitions
-        @definitions ||= {}
-      end
-
-      # 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_or_definition.inspect} without " \
-            'giving it a custom name. Please call register with a custom key like: ' \
-            "#{name}.register(#{path_or_definition.inspect}, as: :my_other_api)"
-          )
-        end
-
-        definition = OpenapiFirst.load(path_or_definition)
-        definitions[as] = definition
-        definition
-      end
-
-      def [](api)
-        definitions.fetch(api) do
-          option = api == :default ? '' : ", as: #{api.inspect}"
-          raise(NotRegisteredError,
-                "API description '#{api.inspect}' not found." \
-                "Please call #{name}.register('myopenapi.yaml'#{option}) " \
-                'once before running tests.')
-        end
-      end
-    end
-  end
-end