openapi_first 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63630ef9a08bcbb2602c05d518f0fc8e2da334ca27e8b5aa06d1165e16c5b1f8
-  data.tar.gz: 7a78262f72e78437b873a2044c81dac22fd76befa8671f457bf0deebe523028e
+  metadata.gz: 177998c88421283a6868e3aa9c5bbbe1eea702bc8b65abb22c28795cb2b7b6a2
+  data.tar.gz: 603118b530e39957ea95086d98a95362e9eb9b9490a63adc7c2bc8e0f7ba7846
 SHA512:
-  metadata.gz: cd59bdb56d8ff90378967cf410ad0ccf0583d69b56bc153bc454773e2637023efb420658b7ba8e71ada6e763d116727b4057e73f6664b0ce2216127759e0aac7
-  data.tar.gz: 128c890b985671e5f882cb58bc0e5fbe49098619321d420d52d49035ad2650b18cc65b9cde246247a21176db23de527aec8b2e7921b693c638297d5057f63802
+  metadata.gz: 58aac32a5c8d7433414f4bf0f2cbf8142376c76d9ad918bf06531f40da0206e870a12e36718ca7763dd273ea18b664799f22acff84df143e36591a19284895fd
+  data.tar.gz: cba873da9fa8b1bf957a47fe34dcd30c50af51185dc83ba78c3f78ad2d5630399555c7d81f89f6e7cb96d9c56771c55aa956900249c2a6700d88869233339f6d

data/CHANGELOG.md

@@ -2,10 +2,16 @@
 
 ## 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). Use `OpenapiFirst::Schema::Hash` to validate multiple parameters schemas and return a single error object.
+- 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

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,10 +127,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, 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.
@@ -149,13 +150,13 @@ To make sure your _whole_ API description is implemented, openapi_first ships wi
 > [!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 tells you about which request/responses are missing.
+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. 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 # (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
@@ -168,7 +169,13 @@ Here is how to set it up with [rack-test](https://github.com/rack/rack-test):
     OpenapiFirst::Test.app(MyApp)
   end
   ```
-3. Run your tests.  The Coverage feature will tell you about missing request/responses. 
+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): 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.
 
@@ -302,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
 ```
@@ -318,9 +325,34 @@ That aside, closer integration with specific frameworks like Sinatra, Hanami, Ro
 
 ## 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

@@ -50,10 +50,8 @@ module OpenapiFirst
       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}"

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

@@ -40,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
@@ -62,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)
@@ -76,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/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

@@ -30,8 +30,7 @@ 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|

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

@@ -7,21 +7,54 @@ module OpenapiFirst
   module Test
     # Methods to use in integration tests
     module Methods
-      def self.[](*)
+      def self.included(base)
+        base.include(DefaultApiMethod)
+        base.include(AssertionMethod)
+      end
+
+      def self.[](application_under_test = nil, api: nil)
         mod = Module.new do
           def self.included(base)
-            OpenapiFirst::Test::Methods.included(base)
+            base.include OpenapiFirst::Test::Methods::AssertionMethod
           end
         end
-        mod.define_method(:app) { OpenapiFirst::Test.app(*) }
+
+        if api
+          mod.define_method(:openapi_first_default_api) { api }
+        else
+          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
 
-      def self.included(base)
-        if Test.minitest?(base)
-          base.include(OpenapiFirst::Test::MinitestHelpers)
-        else
-          base.include(OpenapiFirst::Test::PlainHelpers)
+      # 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:
@@ -103,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  VERSION = '2.6.0'
+  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.6.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Andreas Haller
 bindir: bin
 cert_chain: []
-date: 2025-04-06 00:00:00.000000000 Z
+date: 2025-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hana