faraday-openapi 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b0869a090382dc9f8780e3039255868de82f073a707f57a7d80293c03a1137e
-  data.tar.gz: b21feb28749ab4d2adbd5ce16dbc64dc944c375836af229e17e5fabeff9e63cd
+  metadata.gz: 9f4f143b7d1bfe03b425ccb2b7f9551c0f1432495fd49dd9c98f1308a3099901
+  data.tar.gz: 9c0d8e7542a3144f933fdf292ae1fdabfe1a5210a9cea55ac8e035fe769046fb
 SHA512:
-  metadata.gz: '08cb67099b1fb9a6d3ee9f223f7ecc2d0d1fdabad49eb462c6c4262df3433f8b6267fcc31af83679ccfcf7904d7daa6d16d70d6b471caabc482c05a616b349fd'
-  data.tar.gz: f39f446d15a1c20228a2c1157825eb2b139345e5db794b5e5a5e53ed3b62af7077bcae3ce9d7bcf4233496ae262c9b7ca1e334b298413b0ea30dc70522b06270
+  metadata.gz: 989d36d2f1704d3bbfa45630eac87f0cf992c7d9f2d3e50fe9a5c5aa840ed0065b6e0b6cf5eaba87b30c0c3d6c9c2cbe2a88bf5d5cc77692dae7f7935b40381b
+  data.tar.gz: a4d6196f44f0df42271dc88c266797a7238c14f9d10bf6322955353d2dc8f78397dec5041f8124c90f94df6bf703ab076f85b9f46ce870877bfffd618ae1e056

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.2.0
+
+- Add Faraday::Openapi.register to easily load, cache and reference OADs
+
 ## 0.1.1
 
 Fix URL to homepage, changelog

data/README.md

@@ -7,6 +7,14 @@ You can use this to test your client code or to make sure your mocks do match th
 
 Note that the middleware currently deliberately ignores **unknown** responses with status codes 401 or higher because those usually don't come with a useful response body.
 
+## TL;DR
+
+```ruby
+conn = Faraday.new do |f|
+  f.use :openapi
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -21,33 +29,41 @@ And then execute:
 bundle install
 ```
 
-Or install it yourself as:
+## Usage
 
-```shell
-gem install faraday-openapi
-```
+In order to avoid loading YAML files at inappropriate times you should
+register your API description (OAD) globally and reference it via a Symbol in your client code
 
-## Usage
+```ruby
+# initializer.rb
+
+require 'faraday/openapi'
+Faraday::Openapi.register 'dice-openapi.yaml', as: :dice_api
+
+# Only activate in test env
+Faraday::Openapi::Middleware.enabled = ENV['RACK_ENV'] == 'test'
+```
 
 ```ruby
+# some_client.rb
 require 'faraday/openapi'
 
 conn = Faraday.new do |f|
-  f.use :openapi, 'openapi/openapi.yaml'
+  f.use :openapi, :dice_api
 end
 
 # Or validate only requests
 conn = Faraday.new do |f|
-  f.request :openapi, 'openapi/openapi.yaml'
+  f.request :openapi, :dice_api
 end
 
 # Or validate only responses
 conn = Faraday.new do |f|
-  f.response :openapi, 'openapi/openapi.yaml'
+  f.response :openapi, :dice_api
 end
 ```
 
-You can disable the whole middleware globally:
+You can disable the whole middleware globally via Faraday's conventional default_options as well:
 
 ```ruby
 Faraday::Openapi::Middleware.default_options[:enabled] = false
@@ -67,7 +83,7 @@ See how it works [here](https://bundler.io/guides/creating_gem.html#releasing-th
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [Codeberg](https://codeberg.org/ahx/faraday-openapi).
+Bug reports and pull requests are welcome on [Codeberg](https://codeberg.org/ahx/faraday-openapi) or [Github](https://github.com/ahx/faraday-openapi).
 
 ## License
 

data/lib/faraday/openapi/errors.rb

@@ -10,5 +10,8 @@ module Faraday
 
     # Raised if response does not match API description or is unknown
     class ResponseInvalidError < Error; end
+
+    class AlreadyRegisteredError < Error; end
+    class NotRegisteredError < Error; end
   end
 end

data/lib/faraday/openapi/middleware.rb

@@ -22,11 +22,16 @@ module Faraday
     class Middleware < Faraday::Middleware
       DEFAULT_OPTIONS = { enabled: true }.freeze
 
-      def initialize(app, filepath)
+      def self.enabled=(bool)
+        Faraday::Openapi::Middleware.default_options[:enabled] = bool
+      end
+
+      def initialize(app, path = :default)
         super(app)
-        @filepath = filepath
         @enabled = options.fetch(:enabled, true)
-        @oad = OpenapiFirst.load(filepath) if @enabled
+        return unless @enabled
+
+        @oad = path.is_a?(Symbol) ? Faraday::Openapi[path] : OpenapiFirst.load(path)
       end
 
       def call(env)

data/lib/faraday/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module Faraday
   module Openapi
-    VERSION = '0.1.1'
+    VERSION = '0.2.0'
   end
 end

data/lib/faraday/openapi.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'openapi_first'
 require_relative 'openapi/errors'
 require_relative 'openapi/middleware'
 require_relative 'openapi/version'
@@ -14,18 +15,33 @@ module Faraday
     # After calling this line, the following are both valid ways to set the middleware in a connection:
     # * conn.use Faraday::Openapi::Middleware
     # * conn.use :openapi
-    # Without this line, only the former method is valid.
     Faraday::Middleware.register_middleware(openapi: Faraday::Openapi::Middleware)
     Faraday::Request.register_middleware(openapi: Faraday::Openapi::Middleware)
     Faraday::Response.register_middleware(openapi: Faraday::Openapi::Middleware)
 
-    # Alternatively, you can register your middleware under Faraday::Request or Faraday::Response.
-    # This will allow to load your middleware using the `request` or `response` methods respectively.
-    #
-    # Load middleware with conn.request :openapi
-    # Faraday::Request.register_middleware(openapi: Faraday::Openapi::Middleware)
-    #
-    # Load middleware with conn.response :openapi
-    # Faraday::Response.register_middleware(openapi: Faraday::Openapi::Middleware)
+    @registry = {}
+
+    class << self
+      attr_reader :registry
+    end
+
+    def self.register(filepath, as: :default)
+      raise AlreadyRegisteredError, "API description #{as} is already registered" if registry.key?(as)
+
+      registry[as] = OpenapiFirst.load(filepath)
+    end
+
+    def self.[](key)
+      registry.fetch(key) do
+        message = if registry.empty?
+                    'No API descriptions have been registered. Please register your API description via ' \
+                      "Faraday::Openapi.register('myopenapi.yaml')"
+                  else
+                    "API description #{key.inspect} was not found. Please register your API description via " \
+                      "Faraday::Openapi.register('myopenapi.yaml'#{key == :default ? '' : ", as: #{key.inspect}"})"
+                  end
+        raise NotRegisteredError, message
+      end
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: faraday-openapi
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Andreas Haller
 bindir: bin
 cert_chain: []
-date: 2025-02-18 00:00:00.000000000 Z
+date: 2025-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -93,7 +93,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://codeberg.org/ahx/faraday-openapi/issues
   changelog_uri: https://codeberg.org/ahx/faraday-openapi/src/branch/main/CHANGELOG.md
-  documentation_uri: http://www.rubydoc.info/gems/faraday-openapi/0.1.1
+  documentation_uri: http://www.rubydoc.info/gems/faraday-openapi/0.2.0
   homepage_uri: https://codeberg.org/ahx/faraday-openapi
   rubygems_mfa_required: 'true'
   source_code_uri: https://codeberg.org/ahx/faraday-openapi
@@ -114,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.5
 specification_version: 4
 summary: Validate requests/responses against OpenAPI API descriptions
 test_files: []