api-regulator 0.1.0

data/lib/api_regulator/controller_mixin.rb

@@ -0,0 +1,60 @@
+module ApiRegulator
+  module ControllerMixin
+    def validate_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?
+        raise ApiRegulator::ValidationError.new(validator.errors)
+      end
+    end
+
+    def api_definition
+      return @api_definition if defined?(@api_definition)
+
+      @api_definition ||= self.class.api_definitions.find do |d|
+        d.controller_path == params[:controller] && d.action_name == params[:action]
+      end
+
+      raise "API definition not found for #{params[:controller]}##{params[:action]}" unless @api_definition
+
+      @api_definition
+    end
+
+    def api_params
+      path_params = api_definition.params.select(&:path?).each_with_object({}) do |param, hash|
+        hash[param.name.to_sym] = params[param.name] if params.key?(param.name)
+      end.symbolize_keys
+
+      query_params = api_definition.params.select(&:query?).each_with_object({}) do |param, hash|
+        hash[param.name.to_sym] = params[param.name] if params.key?(param.name)
+      end.symbolize_keys
+
+      body_params = api_definition.params.select(&:body?)
+      permitted_body = body_params.each_with_object({}) do |param, hash|
+        if params.key?(param.name)
+          params.require(param.name).permit(*build_permitted_keys(param.children)).to_h.symbolize_keys
+          hash[param.name.to_sym] = params.require(param.name).permit(*build_permitted_keys(param.children)).to_h.symbolize_keys
+        end
+      end.symbolize_keys
+
+      path_params.merge(query_params).merge(permitted_body).symbolize_keys
+    end
+
+    private
+
+    def build_permitted_keys(params)
+      params.map do |param|
+        if param.children.any?
+          { param.name.to_sym => build_permitted_keys(param.children) }
+        else
+          param.name.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/api_regulator/dsl.rb

@@ -0,0 +1,30 @@
+require "active_support/concern"
+
+module ApiRegulator
+  module DSL
+    extend ActiveSupport::Concern
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def api(controller_class, action, description, &block)
+        @api_definitions ||= []
+
+        api_definition = Api.new(
+          controller_class,
+          action.to_s,
+          description,
+          &block
+        )
+
+        @api_definitions << api_definition
+      end
+
+      def api_definitions
+        @api_definitions || []
+      end
+    end
+  end
+end

data/lib/api_regulator/formats.rb

@@ -0,0 +1,11 @@
+require 'active_model'
+require 'uri'
+
+module ApiRegulator
+  module Formats
+    DATE = ActiveModel::Type::Date::ISO_DATE
+    EMAIL = URI::MailTo::EMAIL_REGEXP
+    ZIP_CODE = /\A\d{5}(-\d{4})?\z/
+    URI = URI::DEFAULT_PARSER.make_regexp
+  end
+end

data/lib/api_regulator/open_api_generator.rb

@@ -0,0 +1,224 @@
+require 'json'
+
+module ApiRegulator
+  class OpenApiGenerator
+    def self.generate(api_definitions)
+      schema = {
+        openapi: '3.1.0', # Explicitly target OpenAPI 3.1.0
+        info: {
+          title: ApiRegulator.configuration.app_name,
+          version: '1.0.0',
+          description: 'Generated by ApiRegulator'
+        },
+        servers: ApiRegulator.configuration.servers,
+        paths: {}
+      }
+
+      add_components(schema)
+      add_security(schema)
+
+      api_definitions.each do |api|
+        add_api_to_schema(schema, api)
+      end
+
+      File.write(ApiRegulator.configuration.docs_path, JSON.pretty_generate(schema))
+      puts "OpenAPI schema generated: #{ApiRegulator.configuration.docs_path}"
+    end
+
+    private
+
+    def self.add_api_to_schema(schema, api)
+      schema[:paths][api.path] ||= {}
+      data = {
+        summary: api.description,
+        description: api.description,
+        operationId: api.operation_id,
+        tags: api.tags,
+        parameters: generate_parameters(api),
+        responses: generate_responses(api)
+      }
+
+      data[:requestBody] = generate_request_body(api) if api.allows_body?
+      data.delete(:requestBody) if data[:requestBody].blank?
+
+      schema[:paths][api.path][api.http_method] = data
+    end
+
+    def self.generate_request_body(api)
+      params = api.params.select(&:body?)
+      return {} if params.empty?
+
+      {
+        required: true,
+        content: {
+          'application/json' => {
+            schema: expand_nested_params(params)
+          }
+        }
+      }
+    end
+
+    def self.expand_nested_params(params)
+      schema = {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+
+      params.each do |param|
+        schema[:properties][param.name] =
+          if param.type == :array
+            generate_array_schema(param)
+          elsif param.children.any?
+            generate_object_schema(param)
+          else
+            generate_param_schema(param)
+          end
+
+        # Add to required array if marked as required
+        schema[:required] << param.name if param.options[:presence]
+      end
+
+      # Remove the required key if it's empty (not needed in OpenAPI spec)
+      schema.delete(:required) if schema[:required].empty?
+      schema
+    end
+
+    def self.generate_array_schema(param)
+      item_schema = param.children.any? ? generate_object_schema(param) : { type: param.item_type }
+
+      {
+        type: 'array',
+        items: item_schema,
+        description: param.desc.presence
+      }.compact
+    end
+
+    def self.generate_object_schema(param)
+      object_schema = expand_nested_params(param.children)
+      object_schema[:description] = param.desc if param.desc.present?
+      object_schema
+    end
+
+    def self.generate_parameters(api)
+      api.params.select(&:parameter?).map do |p|
+        generate_param_schema(p)
+          .merge({
+            name: p.name,
+            required: p.location == :path || p.options[:presence] || false
+          })
+      end
+    end
+
+    def self.generate_param_schema(param)
+      schema = {}
+
+      if param.parameter?
+        schema[:in] = param.location
+        schema[:schema] = { type: param.type.to_s.downcase }
+      else
+        schema[:type] = param.type.to_s.downcase
+      end
+
+      schema[:description] = param.desc if param.desc.present?
+
+
+      # Add length constraints
+      if param.options[:length]
+        schema[:minLength] = param.options[:length][:minimum] if param.options[:length][:minimum]
+        schema[:maxLength] = param.options[:length][:maximum] if param.options[:length][:maximum]
+      end
+
+      # Add format constraints
+      if param.options[:format]
+        if param.options[:format][:with] == Formats::EMAIL
+          schema[:format] = 'email'
+        elsif param.options[:format][:with] == Formats::DATE
+          schema[:format] = 'date'
+        elsif param.options[:format][:with] == Formats::URI
+          schema[:format] = 'uri'
+        elsif param.options[:format][:with].is_a?(Regexp)
+          schema[:pattern] = param.options[:format][:with].source
+        end
+      end
+
+      if param.options[:numericality]
+        schema[:type] = param.options[:only_integer] ? 'integer' : 'number'
+        schema[:minimum] = param.options[:greater_than_or_equal_to] if param.options[:greater_than_or_equal_to]
+        schema[:maximum] = param.options[:less_than_or_equal_to] if param.options[:less_than_or_equal_to]
+        schema[:exclusiveMinimum] = param.options[:greater_than] if param.options[:greater_than]
+        schema[:exclusiveMaximum] = param.options[:less_than] if param.options[:less_than]
+      end
+
+      if param.options[:inclusion]
+        schema[:enum] = param.options[:inclusion][:in]
+      end
+
+      if param.options[:exclusion]
+        schema[:not] = { enum: param.options[:exclusion][:in] }
+      end
+
+      schema[:nullable] = true if param.options[:allow_nil]
+
+      schema
+    end
+
+    def self.generate_responses(api)
+      api.responses.each_with_object({}) do |(status_code, schema), responses|
+        if schema.options[:ref]
+          shared_schema = ApiRegulator.shared_schemas[schema.options[:ref]]
+          raise "Shared schema not found for ref: #{schema.options[:ref]}" unless shared_schema
+
+          responses[status_code.to_s] = {
+            description: shared_schema.description.presence,
+            content: {
+              "application/json" => {
+                schema: { "$ref" => "#/components/schemas/#{schema.options[:ref]}" }
+              }
+            }
+          }.compact
+        else
+          responses[status_code.to_s] = {
+            description: schema.desc.presence,
+            content: {
+              "application/json" => {
+                schema: expand_nested_params(schema.children)
+              }
+            }
+          }.compact
+        end
+      end
+    end
+
+    def self.add_components(schema)
+      add_shared_schemas(schema)
+      add_security_schemes(schema)
+    end
+
+    def self.add_shared_schemas(schema)
+      return unless ApiRegulator.shared_schemas.present?
+
+      schema[:components] ||= {}
+      schema[:components][:schemas] ||= {}
+
+      ApiRegulator.shared_schemas.each do |name, shared_schema|
+        schema[:components][:schemas][name] = expand_nested_params(shared_schema.params).merge(
+          description: shared_schema.description
+        ).compact
+      end
+    end
+
+    def self.add_security_schemes(schema)
+      return unless ApiRegulator.security_schemes.present?
+
+      schema[:components] ||= {}
+      schema[:components][:securitySchemes] = ApiRegulator.security_schemes
+    end
+
+    def self.add_security(schema)
+      return unless ApiRegulator.security.present?
+
+      schema[:security] = ApiRegulator.security
+    end
+  end
+end

data/lib/api_regulator/param.rb

@@ -0,0 +1,55 @@
+module ApiRegulator
+  class Param
+    attr_reader :name, :type, :options, :item_type, :desc, :location, :children
+
+    def initialize(name, type = nil, item_type: nil, desc: "", location: :body, **options, &block)
+      @name = name
+      @type = type&.to_sym || (block_given? ? :object : :string)
+      @item_type = item_type
+      @location = location.to_sym
+      @desc = desc
+      @options = options
+      @children = []
+
+      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, **options, &block)
+      @children << child
+    end
+
+    def ref(ref_name)
+      shared_schema = ApiRegulator.shared_schemas[ref_name]
+      raise "Shared schema #{ref_name} not found" unless shared_schema
+
+      shared_schema.params.each do |shared_param|
+        @children << shared_param
+      end
+    end
+
+    def body?
+      location == :body
+    end
+
+    def query?
+      location == :query
+    end
+
+    def path?
+      location == :path
+    end
+
+    def parameter?
+      [:path, :query].include?(location)
+    end
+
+    def object?
+      type.to_sym == :object
+    end
+
+    def array?
+      type.to_sym == :array
+    end
+  end
+end

data/lib/api_regulator/shared_schema.rb

@@ -0,0 +1,37 @@
+module ApiRegulator
+  class SharedSchema
+    attr_reader :name, :description, :params
+
+    def initialize(name, description, &block)
+      @name = name
+      @description = description
+      @params = []
+      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)
+      @params << param
+    end
+  end
+
+  class << self
+    attr_accessor :security
+
+    def shared_schemas
+      @shared_schemas ||= {}
+    end
+
+    def security_schemes
+      @security_schemes ||= {}
+    end
+
+    def shared_schema(name, description, &block)
+      shared_schemas[name] = SharedSchema.new(name, description, &block)
+    end
+
+    def security_schemes=(scheme)
+      @security_schemes = scheme
+    end
+  end
+end

data/lib/api_regulator/validation_error.rb

@@ -0,0 +1,11 @@
+module ApiRegulator
+  class ValidationError < StandardError
+    attr_reader :errors, :details
+
+    def initialize(errors)
+      @errors = errors
+      @details = errors.messages
+      super("Validation failed with errors, see details")
+    end
+  end
+end

data/lib/api_regulator/validator.rb

@@ -0,0 +1,245 @@
+require "active_model"
+
+module ApiRegulator
+  module AttributeDefinitionMixin
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :defined_attributes, default: []
+      class_attribute :nested_validators, default: {}
+    end
+
+    class_methods do
+      def define_attribute_and_validations(param, parent_key = nil)
+        # Construct the full key
+        full_key = parent_key ? "#{parent_key}.#{param.name}".to_sym : param.name.to_sym
+
+        case param.type
+        when :array
+          define_array_validations(param, full_key)
+        when :object
+          define_object_validations(param, full_key)
+        else
+          define_scalar_validations(param, full_key)
+        end
+      end
+
+      def define_scalar_validations(param, full_key)
+        # Define scalar attributes
+        attribute full_key, param.type if param.type
+        self.defined_attributes += [full_key]
+
+        # Add validations for scalar attributes
+        param.options.each do |option, value|
+          validates full_key, option => value
+        end
+
+        # Add type-specific validations
+        validate -> { validate_boolean(full_key) } if param.type == :boolean
+        validate -> { validate_integer(full_key) } if param.type == :integer
+        validate -> { validate_string(full_key) } if param.type == :string
+      end
+
+      def define_object_validations(param, full_key)
+        # Build nested validator class
+        nested_validator_class = build_nested_validator_class(param.children, param.name, self)
+
+        # Add a custom validation for the nested object
+        validate -> { validate_nested_object(full_key, nested_validator_class, param) }
+
+        # Store the nested validator
+        nested_validators[full_key] = nested_validator_class
+      end
+
+      def define_array_validations(param, full_key)
+        if param.children.any?
+          # Build a nested validator class for array items
+          item_validator_class = build_nested_validator_class(param.children, param.name, self)
+          validate -> { validate_array_of_objects(full_key, item_validator_class, param) }
+        elsif param.item_type
+          # Scalar array with specific item type
+          validate -> { validate_array_of_scalars(full_key, param) }
+        else
+          raise "Arrays must have children or an item_type"
+        end
+      end
+
+      def build_nested_validator_class(children, parent_key, parent_class)
+        # Create a unique class name based on the parent key
+        class_name = "#{parent_key.to_s.camelize}"
+
+        # Return the existing class if already defined
+        if parent_class.const_defined?(class_name, false)
+          return parent_class.const_get(class_name)
+        end
+
+        # Create the nested validator class
+        nested_validator_class = Class.new do
+          include ActiveModel::Model
+          include ActiveModel::Attributes
+          include AttributeDefinitionMixin
+
+          def initialize(attributes = {})
+            @raw_attributes = attributes
+            allowed_attributes = attributes.slice(*self.class.defined_attributes.map(&:to_sym))
+            super(allowed_attributes)
+          end
+        end
+
+        # Add child attributes and validations
+        children.each do |child|
+          nested_validator_class.define_attribute_and_validations(child)
+        end
+
+        # Store the nested class under the parent class namespace
+        parent_class.const_set(class_name, nested_validator_class)
+        nested_validator_class
+      end
+    end
+
+    # Instance methods
+    def validate_array_of_objects(attribute, item_validator_class, param)
+      raw_value = @raw_attributes[attribute]
+      if raw_value.blank?
+        errors.add(attribute, "can't be blank") if param.options[:presence]
+        return
+      end
+      unless raw_value.is_a?(Array)
+        errors.add(attribute, "must be an array")
+        return
+      end
+
+      raw_value.each_with_index do |value, index|
+        unless value.is_a?(Hash)
+          errors.add("#{attribute}[#{index}]", "must be a hash")
+          next
+        end
+
+        validator = item_validator_class.new(value)
+        unless validator.valid?
+          validator.errors.each do |error|
+            nested_attr = "#{attribute}[#{index}].#{error.attribute}"
+            errors.add(nested_attr, error.message)
+          end
+        end
+      end
+    end
+
+    def validate_array_of_scalars(attribute, param)
+      raw_value = @raw_attributes[attribute]
+
+      if raw_value.nil?
+        errors.add(attribute, "can't be blank") if param.options[:presence]
+        return
+      end
+      unless raw_value.is_a?(Array)
+        errors.add(attribute, "must be an array")
+        return
+      end
+
+      raw_value.each_with_index do |value, index|
+        case param.item_type
+        when :string
+          unless value.is_a?(String)
+            errors.add("#{attribute}[#{index}]", "must be a string")
+          end
+        when :integer
+          unless value.is_a?(Integer)
+            errors.add("#{attribute}[#{index}]", "must be an integer")
+          end
+        when :boolean
+          unless [true, false].include?(value)
+            errors.add("#{attribute}[#{index}]", "must be a boolean")
+          end
+        else
+          errors.add("#{attribute}[#{index}]", "has an unsupported type")
+        end
+      end
+    end
+
+    def validate_nested_object(attribute, nested_validator_class, param)
+      raw_value = @raw_attributes[attribute]
+
+      if raw_value.nil?
+        errors.add(attribute, "can't be blank") if param.options[:presence]
+        return
+      end
+      unless raw_value.is_a?(Hash)
+        errors.add(attribute, "must be a hash")
+        return
+      end
+
+      # Initialize the nested validator with the raw value
+      validator = nested_validator_class.new(raw_value)
+
+      # If validation fails, propagate errors
+      unless validator.valid?
+        validator.errors.each do |error|
+          nested_attr = "#{attribute}.#{error.attribute}"
+          errors.add(nested_attr, error.message)
+        end
+      end
+    end
+
+    def validate_boolean(attribute)
+      raw_value = @raw_attributes[attribute]
+      unless [true, false, "true", "false", nil].include?(raw_value)
+        errors.add(attribute, "must be a boolean (true, false, or nil)")
+      end
+    end
+
+    def validate_integer(attribute)
+      raw_value = @raw_attributes[attribute]
+      unless raw_value.to_s =~ /\A[-+]?\d+\z/ || raw_value.nil?
+        errors.add(attribute, "must be an integer")
+      end
+    end
+
+    def validate_string(attribute)
+      raw_value = @raw_attributes[attribute]
+      unless raw_value.is_a?(String) || raw_value.nil?
+        errors.add(attribute, "must be a string")
+      end
+    end
+  end
+
+  class Validator
+    include ActiveModel::Model
+    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
+        validator_class = build_class(api_definition)
+        @validators[[api_definition.controller_path, api_definition.action_name]] = validator_class
+        Validator.const_set(class_name, validator_class)
+      end
+    end
+
+    def self.get(controller, action)
+      @validators[[controller, action]]
+    end
+
+    def self.build_class(api_definition)
+      Class.new(self) do
+        api_definition.params.each do |param|
+          define_attribute_and_validations(param)
+        end
+      end
+    end
+
+    def initialize(attributes = {})
+      @raw_attributes = attributes.deep_symbolize_keys
+      allowed_attributes = attributes.slice(*self.class.defined_attributes.map(&:to_sym))
+      super(allowed_attributes)
+    end
+  end
+end
+
+class FooValidator
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+end

data/lib/api_regulator/version.rb

@@ -0,0 +1,3 @@
+module ApiRegulator
+  VERSION = "0.1.0"
+end

data/lib/api_regulator.rb

@@ -0,0 +1 @@
+require_relative 'api-regulator'