Merge pull request #409 from ahx/register-global

Register OADs globally

Author: ahx

CHANGELOG.md

@@ -5,6 +5,11 @@
 - Breaking: Trailing slashes are no longer ignored in dynamic paths. See [#403](https://github.com/ahx/openapi_first/issues/403).
 - Remove superflous `Test::Coverage.current_run, .plans, .install, .uninstall`
 - Update dependency `openapi_paramters` to >= 0.7.0, because that version fixes unpacking exploded deepObject paramters
+- Add support to register OADs globally via:
+  ```ruby
+  OpenapiFirst.configure { |config| config.register('openapi.yaml')  }
+  ```
+  This removes the necessity to load the OAD in the same place where you use the middlewares and adds a cache for parsed OADs.
 - Add `OpenapiFirst::Test::Configuration#ignore_unknown_response_status=`. When this is set to true, it won't complain about undefined response statuses it sees during a test run. Use with caution.
 - 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.
 

README.md

@@ -4,17 +4,24 @@ openapi_first is a Ruby gem for request / response validation and contract-testi
 
 ## Usage
 
+Configure
+```ruby
+OpenapiFirst.configure do |config|
+  config.register('openapi/openapi.yaml')
+end
+```
+
 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')
+OpenapiFirst::Test.setup do |test|
+  test.register('openapi/openapi.yaml')
 end
 
 require 'my_app'

lib/openapi_first.rb

@@ -3,6 +3,7 @@
 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/definition'
 require_relative 'openapi_first/version'
@@ -11,6 +12,8 @@
 
 # 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
@@ -54,6 +57,7 @@ def self.find_error_response(name)
   # @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)

lib/openapi_first/configuration.rb

@@ -18,6 +18,10 @@ def initialize
       @path = nil
     end
 
+    def register(path_or_definition, as: :default)
+      OpenapiFirst.register(path_or_definition, as:)
+    end
+
     attr_reader :request_validation_error_response, :hooks
     attr_accessor :request_validation_raise_error, :response_validation_raise_error, :path
 

lib/openapi_first/definition.rb

@@ -58,6 +58,10 @@ def key
       "#{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.

lib/openapi_first/middlewares/request_validation.rb

@@ -25,8 +25,8 @@ def initialize(app, spec = nil, options = {})
         @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

lib/openapi_first/middlewares/response_validation.rb

@@ -19,7 +19,8 @@ def initialize(app, spec = nil, options = {})
         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

lib/openapi_first/registry.rb

@@ -0,0 +1,42 @@
+# 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].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 your app.')
+      end
+    end
+  end
+end

lib/openapi_first/test.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'test/configuration'
-require_relative 'test/registry'
+require_relative 'registry'
 
 module OpenapiFirst
   # Test integration