faraday-openapi 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b0869a090382dc9f8780e3039255868de82f073a707f57a7d80293c03a1137e
-  data.tar.gz: b21feb28749ab4d2adbd5ce16dbc64dc944c375836af229e17e5fabeff9e63cd
+  metadata.gz: c5288681710835ea083d20cd469415b3cba5a880cb535692419a0090c0e1432f
+  data.tar.gz: 8e4cbe4290b598c8f9fdb5f15eb1505070c83e1dc8bbc91761a01fb9401d4913
 SHA512:
-  metadata.gz: '08cb67099b1fb9a6d3ee9f223f7ecc2d0d1fdabad49eb462c6c4262df3433f8b6267fcc31af83679ccfcf7904d7daa6d16d70d6b471caabc482c05a616b349fd'
-  data.tar.gz: f39f446d15a1c20228a2c1157825eb2b139345e5db794b5e5a5e53ed3b62af7077bcae3ce9d7bcf4233496ae262c9b7ca1e334b298413b0ea30dc70522b06270
+  metadata.gz: a7e2eb94fdc7d4e6b96d03485cc6364f7f49d6ab4eb1b13928e03015734e40dcf84cfa21e323935794d23d036bc02945926ffb00a007694e1bf7af00d2919707
+  data.tar.gz: 23cfeddcd5ff1dd3cdf7512ae08780799b15bc4ddab990f7edc1246bde72b4cd167bc7b3f8fba76637f702047ec61945b64c5d6eb34ae3fd1808ab80ec1a6c1f

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.3.0
+
+- Breaking change: Use `Faraday::Openapi.enabled=` instead of `Faraday::Openapi::Middleware.enabled=`
+- Fix: Make `f.request :openapi` handle only request, not response validation
+- Support passing a Hash to .register
+
+## 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,36 +29,44 @@ 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.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 all middlewares in this gem globally, which you probably want to do on production.
 
 ```ruby
-Faraday::Openapi::Middleware.default_options[:enabled] = false
+Faraday::Openapi.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

@@ -7,34 +7,24 @@ require_relative 'response'
 
 module Faraday
   module Openapi
-    # This class provides the main implementation for your middleware.
-    # Your middleware can implement any of the following methods:
-    # * on_request - called when the request is being prepared
-    # * on_complete - called when the response is being processed
-    #
-    # Optionally, you can also override the following methods from Faraday::Middleware
-    # * initialize(app, options = {}) - the initializer method
-    # * call(env) - the main middleware invocation method.
-    #   This already calls on_request and on_complete, so you normally don't need to override it.
-    #   You may need to in case you need to "wrap" the request or need more control
-    #   (see "retry" middleware: https://github.com/lostisland/faraday-retry/blob/41b7ea27e30d99ebfed958abfa11d12b01f6b6d1/lib/faraday/retry/middleware.rb#L147).
-    #   IMPORTANT: Remember to call `@app.call(env)` or `super` to not interrupt the middleware chain!
-    class Middleware < Faraday::Middleware
-      DEFAULT_OPTIONS = { enabled: true }.freeze
-
-      def initialize(app, filepath)
+    # Methods for all middlewares
+    module Base
+      def initialize(app, path = :default)
         super(app)
-        @filepath = filepath
-        @enabled = options.fetch(:enabled, true)
-        @oad = OpenapiFirst.load(filepath) if @enabled
+        return unless Openapi.enabled
+
+        @oad = path.is_a?(Symbol) ? Faraday::Openapi[path] : OpenapiFirst.load(path)
       end
 
       def call(env)
-        return app.call(env) unless @enabled
+        return app.call(env) unless Openapi.enabled
 
         super
       end
+    end
 
+    # on_request method to handle request validation
+    module RequestValidation
       # This method will be called when the request is being prepared.
       # You can alter it as you like, accessing things like request_body, request_headers, and more.
       # Refer to Faraday::Env for a list of accessible fields:
@@ -47,7 +37,10 @@ module Faraday
       rescue OpenapiFirst::RequestInvalidError => e
         raise RequestInvalidError, e.message
       end
+    end
 
+    # on_complete method to handle response validation
+    module ResponseValidation
       # This method will be called when the response is being processed.
       # You can alter it as you like, accessing things like response_body, response_headers, and more.
       # Refer to Faraday::Env for a list of accessible fields:
@@ -64,5 +57,21 @@ module Faraday
         raise ResponseInvalidError, e.message
       end
     end
+
+    class Middleware < Faraday::Middleware
+      include Base
+      include RequestValidation
+      include ResponseValidation
+    end
+
+    class RequestMiddleware < Faraday::Middleware
+      include Base
+      include RequestValidation
+    end
+
+    class ResponseMiddleware < Faraday::Middleware
+      include Base
+      include ResponseValidation
+    end
   end
 end

data/lib/faraday/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module Faraday
   module Openapi
-    VERSION = '0.1.1'
+    VERSION = '0.3.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,36 @@ 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)
+    Faraday::Request.register_middleware(openapi: Faraday::Openapi::RequestMiddleware)
+    Faraday::Response.register_middleware(openapi: Faraday::Openapi::ResponseMiddleware)
 
-    # 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 = {}
+    @enabled = true
+
+    class << self
+      attr_reader :registry
+      attr_accessor :enabled
+    end
+
+    def self.register(filepath, as: :default)
+      raise AlreadyRegisteredError, "API description #{as} is already registered" if registry.key?(as)
+
+      oad = filepath.is_a?(Hash) ? OpenapiFirst.parse(filepath) : OpenapiFirst.load(filepath)
+      registry[as] = oad
+    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.3.0
 platform: ruby
 authors:
 - Andreas Haller
 bindir: bin
 cert_chain: []
-date: 2025-02-18 00:00:00.000000000 Z
+date: 2025-03-14 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.3.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: []