api-regulator 0.1.17 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a47dad32fbf8cb59ba8f74f6f78d7bfd6ff3a69a1df21e7ebd81546267838db8
-  data.tar.gz: 4e735d0b0b66b8e671681a3c7e1c0f507fc440a33e2ed4f8a20562e6709ae84b
+  metadata.gz: 2222bdbbc060773ad1c512bfdedd9f7b7acee3920249223236e4468317520353
+  data.tar.gz: 3642bc547ab2ddde180ab34b551d42e496fcc1e49bda947b1f0f9f521a79d498
 SHA512:
-  metadata.gz: 3f0170ac751809bea9a71f1b3216a129446e433bc77bd30527a4ab17411c8dae8b795baa42e01afaa91f7259a4a8bab8cb4f327d18e9c735d48e7d90d1f7a31c
-  data.tar.gz: ccc6b5deba5c6ce6c2f291b3f81aefb0f199356cf15ca30f6dc354767b400d96531953a9c576977b73603b12a607879be5208d1577d6d9c0254a7651afafddef
+  metadata.gz: 22a0cb6db6778f6fdbe0cc795658628120c57907a513c73bdd52f3d138135d8895b1044931e9392e67e265bf5e112b22003837c924d56717f5043494a68401e0
+  data.tar.gz: e728660a393d6f57028fa26732b160c94bcc7e7567bc6957fa0d55322de4cfac490c4a742136c53f1119df79bd5d6ea088d393fcc363115e91734b7e858adac4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    api-regulator (0.1.17)
+    api-regulator (0.1.19)
       activemodel (~> 8.0)
       activesupport (~> 8.0)
 
@@ -88,7 +88,7 @@ GEM
     connection_pool (2.5.0)
     crass (1.0.6)
     date (3.4.1)
-    diff-lcs (1.5.1)
+    diff-lcs (1.6.0)
     drb (2.2.1)
     erubi (1.13.1)
     globalid (1.2.1)
@@ -100,7 +100,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    logger (1.6.5)
+    logger (1.6.6)
     loofah (2.24.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
@@ -113,7 +113,7 @@ GEM
     mini_mime (1.1.5)
     mini_portile2 (2.8.8)
     minitest (5.25.4)
-    net-imap (0.5.5)
+    net-imap (0.5.6)
       date
       net-protocol
     net-pop (0.1.2)
@@ -135,7 +135,7 @@ GEM
       date
       stringio
     racc (1.8.1)
-    rack (3.1.9)
+    rack (3.1.10)
     rack-session (2.1.0)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)

data/lib/api_regulator/api.rb

@@ -16,8 +16,8 @@ module ApiRegulator
       instance_eval(&block) if block_given?
     end
 
-    def param(name, type = nil, item_type: nil, desc: "", location: :body, **options, &block)
-      param = Param.new(name, type, item_type: item_type, desc: desc, location: location, api: self, **options, &block)
+    def param(name, type = nil, item_type: nil, desc: "", location: :body, allow_arbitrary_keys: false, **options, &block)
+      param = Param.new(name, type, item_type: item_type, desc: desc, location: location, api: self, allow_arbitrary_keys: allow_arbitrary_keys, **options, &block)
       @params << param
     end
 
@@ -100,8 +100,12 @@ module ApiRegulator
       @api_definitions ||= []
     end
 
+    def set_api_definitions(defs)
+      @api_definitions = defs
+    end
+
     def reset_api_definitions
-      @api_definitions = []
+      set_api_definitions([])
     end
   end
 end

data/lib/api_regulator/controller_mixin.rb

@@ -1,15 +1,16 @@
 module ApiRegulator
   module ControllerMixin
     def validate_params!
+      check_for_extra_params!
+
       validator_class = Validator.get(params[:controller], params[:action])
 
       unless validator_class
         raise "No validator found for HTTP method #{request.method} and API path #{api_definition.path}"
       end
-
       validator = validator_class.new(api_params)
       unless validator.valid?(params[:action].to_sym)
-        raise ApiRegulator::ValidationError.new(validator.errors)
+        raise ApiRegulator::InvalidParams.new(validator.errors)
       end
     end
 
@@ -63,5 +64,17 @@ module ApiRegulator
         end
       end
     end
+
+    def check_for_extra_params!
+      actual_keys = Validator.flatten_keys(params.to_unsafe_h)
+
+      # Identify extra keys
+      extra_keys = Validator.find_extra_keys(actual_keys, api_definition.params)
+
+      # Raise an error if there are unexpected keys
+      unless extra_keys.empty?
+        raise ApiRegulator::UnexpectedParams.new(extra_keys)
+      end
+    end
   end
 end

data/lib/api_regulator/open_api_generator.rb

@@ -99,6 +99,7 @@ module ApiRegulator
     def self.generate_object_schema(param)
       object_schema = expand_nested_params(param.children)
       object_schema[:description] = param.desc if param.desc.present?
+      object_schema[:type] = param.allow_nil? ? ['object', 'null'] : 'object'
       object_schema
     end
 
@@ -119,10 +120,17 @@ module ApiRegulator
 
       if param.parameter?
         schema[:in] = param.location
-        schema[:schema] = { type: param.type.to_s.downcase }
+        schema[:schema] = { type: param.schema_type }
+        if param.type == :object && param.allow_arbitrary_keys
+          schema[:schema][:additionalProperties] = true
+        end
+        if param.type == :object && param.location == :query
+          schema[:explode] = true
+          schema[:style] = "deepObject"
+        end
         generate_param_schema_details(param, schema[:schema])
       else
-        schema[:type] = param.type.to_s.downcase
+        schema[:type] = param.schema_type
         generate_param_schema_details(param, schema)
       end
       schema
@@ -151,7 +159,7 @@ module ApiRegulator
       end
 
       if numericality = param.options[:numericality]
-        schema[:type] = numericality[:only_integer] || schema[:type] == "integer" ? 'integer' : 'number'
+        schema[:type] = numericality[:only_integer] || param.type == :integer ? 'integer' : 'number'
         schema[:minimum] = numericality[:greater_than_or_equal_to] if numericality[:greater_than_or_equal_to]
         schema[:maximum] = numericality[:less_than_or_equal_to] if numericality[:less_than_or_equal_to]
         schema[:exclusiveMinimum] = numericality[:greater_than] if numericality[:greater_than]

data/lib/api_regulator/param.rb

@@ -1,8 +1,8 @@
 module ApiRegulator
   class Param
-    attr_reader :name, :type, :options, :item_type, :desc, :location, :children, :api
+    attr_reader :name, :type, :options, :item_type, :desc, :location, :children, :api, :allow_arbitrary_keys
 
-    def initialize(name, type = nil, item_type: nil, desc: "", location: :body, api: nil, **options, &block)
+    def initialize(name, type = nil, item_type: nil, desc: "", location: :body, api: nil, allow_arbitrary_keys: false, **options, &block)
       @name = name
       @type = type&.to_sym || (block_given? ? :object : :string)
       @item_type = item_type
@@ -11,12 +11,13 @@ module ApiRegulator
       @options = options
       @children = []
       @api = api
+      @allow_arbitrary_keys = allow_arbitrary_keys
 
       instance_eval(&block) if block_given?
     end
 
-    def param(name, type = nil, item_type: nil, desc: "", location: :body, **options, &block)
-      child = Param.new(name, type, item_type: item_type, desc: desc, location: location, api: api, **options, &block)
+    def param(name, type = nil, item_type: nil, desc: "", location: :body, allow_arbitrary_keys: false, **options, &block)
+      child = Param.new(name, type, item_type: item_type, desc: desc, location: location, api: api, allow_arbitrary_keys: allow_arbitrary_keys, **options, &block)
       @children << child
     end
 
@@ -46,7 +47,9 @@ module ApiRegulator
       return false if @options[:presence].nil?
 
       if @options[:presence].is_a?(Hash)
-        if context.nil?
+        if @options[:presence].key?(:allow_nil)
+          !@options[:presence][:allow_nil]
+        elsif context.nil?
           true # No context provided
         elsif @options[:presence][:required_on].present?
           Array(@options[:presence][:required_on]).map(&:to_sym).include?(context.to_sym)
@@ -60,6 +63,54 @@ module ApiRegulator
       end
     end
 
+    def allow_nil?
+      @options.any? do |_, opts|
+        opts.is_a?(Hash) && opts[:allow_nil]
+      end
+    end
+
+    def allowed_keys(parent_key = nil)
+      key = parent_key.present? ? "#{parent_key}.#{name}" : name.to_s
+      key += "[]" if array?
+
+      if options[:ref]
+        shared_schema = ApiRegulator.shared_schema(options[:ref])
+        shared_schema.params.flat_map do |param|
+          param.allowed_keys
+        end
+      elsif children.any?
+        key = nil if key == "root"
+        child_keys = children.flat_map do |child|
+          child.allowed_keys(key)
+        end
+        child_keys << key if allow_nil?
+        child_keys
+      else
+        key
+      end
+    end
+
+    def allowed_arbitrary_keys(parent_key = nil)
+      key = parent_key.present? ? "#{parent_key}.#{name}" : name.to_s
+      key += "[]" if array?
+
+      if options[:ref]
+        shared_schema = ApiRegulator.shared_schema(options[:ref])
+        shared_schema.params.flat_map do |param|
+          param.allowed_arbitrary_keys
+        end.compact
+      elsif children.any?
+        key = nil if key == "root"
+        child_keys = children.flat_map do |child|
+          child.allowed_arbitrary_keys(key)
+        end.compact
+        child_keys << key if allow_nil? && allow_arbitrary_keys
+        child_keys
+      else
+        key if allow_arbitrary_keys
+      end
+    end
+
     def body?
       location == :body
     end
@@ -83,5 +134,13 @@ module ApiRegulator
     def array?
       type.to_sym == :array
     end
+
+    def schema_type
+      if allow_nil?
+        [type.to_s.downcase, "null"]
+      else
+        type.to_s.downcase
+      end
+    end
   end
 end

data/lib/api_regulator/shared_schema.rb

@@ -10,8 +10,8 @@ module ApiRegulator
       instance_eval(&block) if block_given?
     end
 
-    def param(name, type = nil, item_type: nil, desc: "", location: :body, **options, &block)
-      param = Param.new(name, type, item_type: item_type, desc: desc, location: location, **options, &block)
+    def param(name, type = nil, item_type: nil, desc: "", location: :body, allow_arbitrary_keys: false, **options, &block)
+      param = Param.new(name, type, item_type: item_type, desc: desc, location: location, allow_arbitrary_keys: allow_arbitrary_keys, **options, &block)
       @params << param
     end
 

data/lib/api_regulator/validation_error.rb

@@ -1,6 +1,21 @@
 module ApiRegulator
   class ValidationError < StandardError
-    attr_reader :errors, :details
+    attr_reader :details
+  end
+
+  class UnexpectedParams < ValidationError
+    def initialize(unexpected_keys)
+      @details = {}
+      unexpected_keys.each do |key|
+        @details[key] = ["is unexpected"]
+      end
+
+      super("Unexpected parameters")
+    end
+  end
+
+  class InvalidParams < ValidationError
+    attr_reader :errors
 
     def initialize(errors)
       @errors = errors

data/lib/api_regulator/validator.rb

@@ -193,11 +193,8 @@ module ApiRegulator
     def validate_nested_object(attribute, nested_validator_class, param)
       raw_value = @raw_attributes[attribute]
 
-      # Skip validation if optional and not present
-      return if raw_value.nil? && param.options[:optional]
-
       if raw_value.nil?
-        errors.add(attribute, "can't be blank") if param.options[:presence]
+        errors.add(attribute, "can't be blank") if param.required?(validation_context)
         return
       end
 
@@ -245,13 +242,10 @@ module ApiRegulator
     include ActiveModel::Attributes
     include AttributeDefinitionMixin
 
-    @validators = {}
-
     def self.build_all(api_definitions)
       api_definitions.each do |api_definition|
-        class_name = "#{api_definition.controller_path}/#{api_definition.action_name}".gsub("/", "_").camelcase
+        class_name = build_class_name(api_definition.controller_path, api_definition.action_name)
         validator_class = build_class(api_definition.params, api_definition.action_name)
-        @validators[[api_definition.controller_path, api_definition.action_name]] = validator_class
         Validator.const_set(class_name, validator_class)
       end
     end
@@ -259,17 +253,23 @@ module ApiRegulator
     def self.build_response_validators(api_definitions = ApiRegulator.api_definitions)
       api_definitions.each do |api_definition|
         api_definition.responses.each do |code, params|
-          class_name = "#{api_definition.controller_path}/#{api_definition.action_name}/Response#{code}".gsub("/", "_").camelcase
-
+          class_name = build_class_name(api_definition.controller_path, api_definition.action_name, code)
           validator_class = build_class(params.children, api_definition.action_name)
-          @validators[[api_definition.controller_path, api_definition.action_name, code]] = validator_class
           Validator.const_set(class_name, validator_class)
         end
       end
     end
 
-    def self.get(controller, action, code = nil)
-      @validators[[controller.to_s, action.to_s, code].compact]
+    def self.build_class_name(controller_path, action, code = nil, prefix: false)
+      class_name = "#{controller_path}/#{action}"
+      class_name += "/Response#{code}" if code.present?
+      class_name = class_name.gsub("/", "_").camelcase
+      class_name = "ApiRegulator::Validator::" + class_name if prefix
+      class_name
+    end
+
+    def self.get(controller_path, action, code = nil)
+      build_class_name(controller_path, action, code, prefix: true).constantize
     end
 
     def self.build_class(params, action_name)
@@ -294,6 +294,10 @@ module ApiRegulator
     end
 
     def self.validate_response(controller, action, code, body)
+      body = {} if body.empty?
+
+      check_for_extra_response_params!(controller, action, code, body)
+
       validator_class = get(controller, action, code)
 
       unless validator_class
@@ -302,12 +306,60 @@ module ApiRegulator
 
       validator = validator_class.new(body)
       unless validator.valid?(:response) # using :response for validation context
-        raise ApiRegulator::ValidationError.new(validator.errors)
+        raise ApiRegulator::InvalidParams.new(validator.errors)
       end
     end
 
-    def self.reset_validators
-      @validators = {}
+
+    def self.check_for_extra_response_params!(controller, action, code, body)
+      actual_keys = flatten_keys(body)
+
+      api_definition ||= ApiRegulator.api_definitions.find do |d|
+        d.controller_path == controller && d.action_name == action.to_s
+      end
+      response_definition = api_definition.responses[code]
+
+      # Identify extra keys
+      extra_keys = find_extra_keys(actual_keys, [response_definition])
+
+      # Raise an error if there are unexpected keys
+      unless extra_keys.empty?
+        raise ApiRegulator::UnexpectedParams.new(extra_keys)
+      end
+    end
+
+    def self.flatten_keys(hash, parent_key = nil)
+      hash.each_with_object([]) do |(key, value), keys|
+        next if ["controller", "action"].include?(key)
+
+        full_key = parent_key ? "#{parent_key}.#{key}" : key.to_s
+
+        if value.is_a?(Hash)
+          keys.concat(flatten_keys(value, full_key))
+        elsif value.is_a?(Array)
+          value.each_with_index do |item, index|
+            if item.is_a?(Hash)
+              keys.concat(flatten_keys(item, "#{full_key}[#{index}]"))
+            else
+              keys << "#{full_key}[#{index}]"
+            end
+          end
+        else
+          keys << full_key
+        end
+      end
+    end
+
+    def self.find_extra_keys(actual_keys, params)
+      allowed_keys = params.flat_map(&:allowed_keys)
+      allowed_arbitrary_keys = params.flat_map(&:allowed_arbitrary_keys).compact
+      extras = []
+      actual_keys.each do |key|
+        next if allowed_keys.include?(key.gsub(/\[\d+\]/, "[]"))
+        next if allowed_arbitrary_keys.any? { |aribitrary_key| key.starts_with?(aribitrary_key) }
+        extras << key
+      end
+      extras
     end
   end
 end

data/lib/api_regulator/version.rb

@@ -1,3 +1,3 @@
 module ApiRegulator
-  VERSION = "0.1.17"
+  VERSION = "0.1.19"
 end

data/lib/api_regulator/webhook.rb

@@ -13,8 +13,8 @@ module ApiRegulator
       instance_eval(&block) if block_given?
     end
 
-    def param(name, type = nil, item_type: nil, desc: "", location: :body, **options, &block)
-      param = Param.new(name, type, item_type: item_type, desc: desc, location: location, **options, &block)
+    def param(name, type = nil, item_type: nil, desc: "", location: :body, allow_arbitrary_keys: false, **options, &block)
+      param = Param.new(name, type, item_type: item_type, desc: desc, location: location, allow_arbitrary_keys: allow_arbitrary_keys, **options, &block)
       @params << param
     end
 

data/lib/tasks/api_regulator_tasks.rake

@@ -3,6 +3,9 @@ require 'yaml'
 namespace :api_docs do
   desc 'Generate OpenAPI schema'
   task generate: :environment do
+    # Set an empty api key if none is provided
+    ENV['RDME_API_KEY'] ||= ''
+
     Rails.application.eager_load! # Ensure all controllers and API definitions are loaded
 
     ApiRegulator::OpenApiGenerator.generate(ApiRegulator.api_definitions)
@@ -11,7 +14,7 @@ namespace :api_docs do
   desc "Upload OpenAPI schema to ReadMe"
   task :upload => :environment do
     # ReadMe API key and version
-    readme_api_key = ENV['RDME_API_KEY'] || raise("RDME_API_KEY is not set")
+    readme_api_key = ENV['RDME_API_KEY'].presence || raise("RDME_API_KEY is not set")
 
     # ReadMe API endpoint
     readme_api_endpoint = "https://dash.readme.com/api/v1/api-specification"
@@ -71,7 +74,7 @@ namespace :api_docs do
   desc "Upload custom pages to ReadMe"
   task :upload_pages => :environment do
     # Configuration
-    readme_api_key = ENV['RDME_API_KEY'] || raise("RDME_API_KEY is not set")
+    readme_api_key = ENV['RDME_API_KEY'].presence || raise("RDME_API_KEY is not set")
     base_readme_api_endpoint = "https://dash.readme.com/api/v1/docs"
 
     # Discover all documentation files
@@ -130,7 +133,7 @@ namespace :api_docs do
   desc "View all categories on Readme.com"
   task :fetch_categories => :environment do
     # Configuration
-    readme_api_key = ENV['RDME_API_KEY'] || raise("RDME_API_KEY is not set")
+    readme_api_key = ENV['RDME_API_KEY'].presence || raise("RDME_API_KEY is not set")
     readme_categories_api_endpoint = "https://dash.readme.com/api/v1/categories"
 
     # Build the API request
@@ -173,7 +176,7 @@ namespace :api_docs do
   end
 
   def check_if_page_exists(slug)
-    readme_api_key = ENV['RDME_API_KEY'] || raise("RDME_API_KEY is not set")
+    readme_api_key = ENV['RDME_API_KEY'].presence || raise("RDME_API_KEY is not set")
     uri = URI.parse("https://dash.readme.com/api/v1/docs/#{slug}")
     request = Net::HTTP::Get.new(uri)
     request["Authorization"] = "Basic #{Base64.strict_encode64(readme_api_key)}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api-regulator
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.1.19
 platform: ruby
 authors:
 - Geoff Massanek
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-07 00:00:00.000000000 Z
+date: 2025-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport