api-regulator 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8474dc3c3898732b6e48a0b2c1722ecc13735e95474b01d9c4223be2cc461653
-  data.tar.gz: 541a39193368ff06b3932f869e75d27a50375ae5c2acd772e0276aa2c892bc8a
+  metadata.gz: 805a7ee5772352ec9d9f1e8bea5f6f79ef5dd67c170bfb3ca62898a2685a0067
+  data.tar.gz: 75d36c102ed4f9494cfb8f97be7cca09de8206006fb1ca28352734f15ecc29d1
 SHA512:
-  metadata.gz: 67f74a784f20dc965e53a838c6ea8d068242cf77fd7aa7508c6e7e427efd4fef9f29a8242ab737f375b7accc84192551acc40036cfeb9778c1899731510cc102
-  data.tar.gz: 732b45b1592042bc7259f82d84b396583a74acb92daac22636d1edddc9f2b41771eea4226459b6709ac109b8ed430a6838ef76a592d2c2742d6ae5dcae3e2b36
+  metadata.gz: 45f235550878457b9af59dc1f3d4d2b70ac8afe581dfc35d9f5a13a37da67eb17ef9f6e4da1d877352eca27229847367909645f66d20cdaa807d9c52f133c894
+  data.tar.gz: a67c9b219a20a6e9dffd99fa33f285222452621b99c7304ffd3e7366f86fb8046505857c27047a86161bf3232cf07b81e35a75a7375fe7bace8a0708982ba9c1

data/.github/workflows/spec.yml

@@ -0,0 +1,35 @@
+name: Run Specs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      # Checkout the code
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      # Set up Ruby
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2' # Specify your gem's Ruby version
+          bundler-cache: true # Cache gems to speed up the workflow
+
+      # Install dependencies
+      - name: Install dependencies
+        run: bundle install
+
+      # Run RSpec tests
+      - name: Run specs
+        run: bundle exec rspec
+

data/.gitignore

@@ -14,3 +14,4 @@ spec/support/log/**
 spec/tmp
 
 api-regulator-*.gem
+.byebug_history

data/Gemfile.lock

@@ -1,36 +1,36 @@
 PATH
   remote: .
   specs:
-    api-regulator (0.1.0)
+    api-regulator (0.1.2)
       activemodel
       activesupport
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (7.2.2)
-      actionpack (= 7.2.2)
-      activesupport (= 7.2.2)
+    actioncable (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       nio4r (~> 2.0)
       websocket-driver (>= 0.6.1)
       zeitwerk (~> 2.6)
-    actionmailbox (7.2.2)
-      actionpack (= 7.2.2)
-      activejob (= 7.2.2)
-      activerecord (= 7.2.2)
-      activestorage (= 7.2.2)
-      activesupport (= 7.2.2)
+    actionmailbox (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activejob (= 7.2.2.1)
+      activerecord (= 7.2.2.1)
+      activestorage (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       mail (>= 2.8.0)
-    actionmailer (7.2.2)
-      actionpack (= 7.2.2)
-      actionview (= 7.2.2)
-      activejob (= 7.2.2)
-      activesupport (= 7.2.2)
+    actionmailer (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      actionview (= 7.2.2.1)
+      activejob (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       mail (>= 2.8.0)
       rails-dom-testing (~> 2.2)
-    actionpack (7.2.2)
-      actionview (= 7.2.2)
-      activesupport (= 7.2.2)
+    actionpack (7.2.2.1)
+      actionview (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       nokogiri (>= 1.8.5)
       racc
       rack (>= 2.2.4, < 3.2)
@@ -39,35 +39,35 @@ GEM
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
       useragent (~> 0.16)
-    actiontext (7.2.2)
-      actionpack (= 7.2.2)
-      activerecord (= 7.2.2)
-      activestorage (= 7.2.2)
-      activesupport (= 7.2.2)
+    actiontext (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activerecord (= 7.2.2.1)
+      activestorage (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       globalid (>= 0.6.0)
       nokogiri (>= 1.8.5)
-    actionview (7.2.2)
-      activesupport (= 7.2.2)
+    actionview (7.2.2.1)
+      activesupport (= 7.2.2.1)
       builder (~> 3.1)
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
-    activejob (7.2.2)
-      activesupport (= 7.2.2)
+    activejob (7.2.2.1)
+      activesupport (= 7.2.2.1)
       globalid (>= 0.3.6)
-    activemodel (7.2.2)
-      activesupport (= 7.2.2)
-    activerecord (7.2.2)
-      activemodel (= 7.2.2)
-      activesupport (= 7.2.2)
+    activemodel (7.2.2.1)
+      activesupport (= 7.2.2.1)
+    activerecord (7.2.2.1)
+      activemodel (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       timeout (>= 0.4.0)
-    activestorage (7.2.2)
-      actionpack (= 7.2.2)
-      activejob (= 7.2.2)
-      activerecord (= 7.2.2)
-      activesupport (= 7.2.2)
+    activestorage (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activejob (= 7.2.2.1)
+      activerecord (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       marcel (~> 1.0)
-    activesupport (7.2.2)
+    activesupport (7.2.2.1)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -99,7 +99,7 @@ GEM
     irb (1.14.1)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    logger (1.6.1)
+    logger (1.6.3)
     loofah (2.23.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
@@ -111,7 +111,7 @@ GEM
     marcel (1.0.4)
     mini_mime (1.1.5)
     mini_portile2 (2.8.8)
-    minitest (5.25.2)
+    minitest (5.25.4)
     net-imap (0.5.1)
       date
       net-protocol
@@ -122,10 +122,10 @@ GEM
     net-smtp (0.5.0)
       net-protocol
     nio4r (2.7.4)
-    nokogiri (1.16.8)
+    nokogiri (1.17.2)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    nokogiri (1.16.8-arm64-darwin)
+    nokogiri (1.17.2-arm64-darwin)
       racc (~> 1.4)
     psych (5.2.0)
       stringio
@@ -137,30 +137,30 @@ GEM
       rack (>= 1.3)
     rackup (2.2.1)
       rack (>= 3)
-    rails (7.2.2)
-      actioncable (= 7.2.2)
-      actionmailbox (= 7.2.2)
-      actionmailer (= 7.2.2)
-      actionpack (= 7.2.2)
-      actiontext (= 7.2.2)
-      actionview (= 7.2.2)
-      activejob (= 7.2.2)
-      activemodel (= 7.2.2)
-      activerecord (= 7.2.2)
-      activestorage (= 7.2.2)
-      activesupport (= 7.2.2)
+    rails (7.2.2.1)
+      actioncable (= 7.2.2.1)
+      actionmailbox (= 7.2.2.1)
+      actionmailer (= 7.2.2.1)
+      actionpack (= 7.2.2.1)
+      actiontext (= 7.2.2.1)
+      actionview (= 7.2.2.1)
+      activejob (= 7.2.2.1)
+      activemodel (= 7.2.2.1)
+      activerecord (= 7.2.2.1)
+      activestorage (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       bundler (>= 1.15.0)
-      railties (= 7.2.2)
+      railties (= 7.2.2.1)
     rails-dom-testing (2.2.0)
       activesupport (>= 5.0.0)
       minitest
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.6.1)
+    rails-html-sanitizer (1.6.2)
       loofah (~> 2.21)
       nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
-    railties (7.2.2)
-      actionpack (= 7.2.2)
-      activesupport (= 7.2.2)
+    railties (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
       irb (~> 1.13)
       rackup (>= 1.0.0)
       rake (>= 12.2)
@@ -192,13 +192,13 @@ GEM
       rspec-mocks (~> 3.10)
       rspec-support (~> 3.10)
     rspec-support (3.13.1)
-    securerandom (0.3.2)
+    securerandom (0.4.0)
     stringio (3.1.2)
     thor (1.3.2)
     timeout (0.4.2)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    useragent (0.16.10)
+    useragent (0.16.11)
     websocket-driver (0.7.6)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)

data/README.md

@@ -48,9 +48,8 @@ Run `bundle install` to install the gem.
 
    ```ruby
    ApiRegulator.configure do |config|
-     config.base_controller = "Api::ApplicationController" # Set your base API controller
      config.api_base_url = "/api/v1" # Set a common base path for your API endpoints
-     config.docs_path = Rails.root.join("doc", "openapi.json").to_s # Path for OpenAPI JSON file
+     config.docs_path = Rails.root.join("doc").to_s # Path for folder for docs
      config.app_name = "My API" # shows in docs
      config.rdme_api_id = ENV["RDME_API_ID"] # Optional: ReadMe API ID for schema uploads
      config.servers = [
@@ -111,7 +110,7 @@ end
 Define reusable schemas for common responses in your initializer:
 
 ```ruby
-ApiRegulator.shared_schema :validation_errors, "Validation error response" do
+ApiRegulator.register_shared_schema :validation_errors, "Validation error response" do
   param :errors, :array, desc: "Array of validation errors", items_type: :string
 end
 ```

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "api/regulator"
+require "api-regulator"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/lib/api-regulator.rb

@@ -5,10 +5,12 @@ require_relative 'api_regulator/dsl'
 require_relative 'api_regulator/formats'
 require_relative 'api_regulator/open_api_generator'
 require_relative 'api_regulator/param'
+require_relative 'api_regulator/security'
 require_relative 'api_regulator/shared_schema'
 require_relative 'api_regulator/validation_error'
 require_relative 'api_regulator/validator'
 require_relative 'api_regulator/version'
+require_relative 'api_regulator/webhook'
 
 # Load tasks if Rails is present
 if defined?(Rake)
@@ -28,8 +30,8 @@ module ApiRegulator
 
     def prepare_validators
       Rails.application.eager_load! # Ensure all controllers and API definitions are loaded
-      api_definitions = ApiRegulator.configuration.base_controller_klass.descendants.flat_map(&:api_definitions)
-      ApiRegulator::Validator.build_all(api_definitions)
+
+      ApiRegulator::Validator.build_all(ApiRegulator.api_definitions)
     end
   end
 end

data/lib/api_regulator/api.rb

@@ -1,13 +1,14 @@
 module ApiRegulator
   class Api
-    attr_reader :controller_class, :controller_path, :controller_name, :action_name, :description, :params, :responses
+    attr_reader :controller_class, :controller_path, :controller_name, :action_name, :description, :title, :params, :responses
 
-    def initialize(controller_class, action_name, description, &block)
+    def initialize(controller_class, action_name, desc: nil, title: nil, &block)
       @controller_class = controller_class
       @controller_name = controller_class.name
       @controller_path = controller_class.controller_path
       @action_name = action_name.to_s
-      @description = description
+      @description = desc
+      @title = title
 
       @params = []
       @responses = {}
@@ -20,11 +21,20 @@ module ApiRegulator
       @params << param
     end
 
-    def ref(ref_name)
-      shared_schema = ApiRegulator.shared_schemas[ref_name]
+    def ref(ref_name, except: [], only: [])
+      shared_schema = ApiRegulator.shared_schema(ref_name)
       raise "Shared schema #{ref_name} not found" unless shared_schema
 
-      shared_schema.params.each do |shared_param|
+      # Filter parameters based on `only` or `except` options
+      filtered_params = shared_schema.params
+
+      if only.any?
+        filtered_params = filtered_params.select { |param| only.include?(param.name) }
+      elsif except.any?
+        filtered_params = filtered_params.reject { |param| except.include?(param.name) }
+      end
+
+      filtered_params.each do |shared_param|
         @params << shared_param
       end
     end
@@ -79,4 +89,14 @@ module ApiRegulator
       http_method != "get"
     end
   end
+
+  class << self
+    def api_definitions
+      @api_definitions ||= []
+    end
+
+    def reset_api_definitions
+      @api_definitions = []
+    end
+  end
 end

data/lib/api_regulator/configuration.rb

@@ -1,18 +1,13 @@
 module ApiRegulator
   class Configuration
-    attr_accessor :base_controller, :api_base_url, :app_name, :docs_path, :rdme_api_id, :servers
+    attr_accessor :api_base_url, :app_name, :docs_path, :rdme_api_id, :servers
 
     def initialize
       # Set default values
-      @base_controller = "ApplicationController"
       @api_base_url = "api/v1"
       @app_name = "API Documentation"
-      @docs_path = "openapi.json"
+      @docs_path = "doc"
       @servers = []
     end
-
-    def base_controller_klass
-      ApiRegulator.configuration.base_controller.constantize
-    end
   end
 end

data/lib/api_regulator/dsl.rb

@@ -9,17 +9,24 @@ module ApiRegulator
     end
 
     module ClassMethods
-      def api(controller_class, action, description, &block)
+      def api(controller_class, action, desc: nil, title: nil, &block)
         @api_definitions ||= []
 
         api_definition = Api.new(
           controller_class,
           action.to_s,
-          description,
+          desc: desc,
+          title: title,
           &block
         )
 
         @api_definitions << api_definition
+        ApiRegulator.api_definitions << api_definition
+      end
+
+      def webhook(event_name, desc: nil, title: nil, tags: [], &block)
+        webhook = Webhook.new(event_name, desc: desc, title: title, tags: tags, &block)
+        ApiRegulator.webhook_definitions << webhook
       end
 
       def api_definitions

data/lib/api_regulator/open_api_generator.rb

@@ -16,13 +16,15 @@ module ApiRegulator
 
       add_components(schema)
       add_security(schema)
+      add_webhooks(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}"
+      schema_path = "#{ApiRegulator.configuration.docs_path}/openapi.json"
+      File.write(schema_path, JSON.pretty_generate(schema))
+      puts "OpenAPI schema generated: #{schema_path}"
     end
 
     private
@@ -30,13 +32,13 @@ module ApiRegulator
     def self.add_api_to_schema(schema, api)
       schema[:paths][api.path] ||= {}
       data = {
-        summary: api.description,
-        description: api.description,
+        summary: api.title,
+        description: api.description.presence || api.title,
         operationId: api.operation_id,
         tags: api.tags,
         parameters: generate_parameters(api),
         responses: generate_responses(api)
-      }
+      }.compact
 
       data[:requestBody] = generate_request_body(api) if api.allows_body?
       data.delete(:requestBody) if data[:requestBody].blank?
@@ -113,16 +115,20 @@ module ApiRegulator
     def self.generate_param_schema(param)
       schema = {}
 
+      schema[:description] = param.desc if param.desc.present?
+
       if param.parameter?
         schema[:in] = param.location
         schema[:schema] = { type: param.type.to_s.downcase }
+        generate_param_schema_details(param, schema[:schema])
       else
         schema[:type] = param.type.to_s.downcase
+        generate_param_schema_details(param, schema)
       end
+      schema
+    end
 
-      schema[:description] = param.desc if param.desc.present?
-
-
+    def self.generate_param_schema_details(param, schema)
       # Add length constraints
       if param.options[:length]
         schema[:minLength] = param.options[:length][:minimum] if param.options[:length][:minimum]
@@ -142,12 +148,12 @@ module ApiRegulator
         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]
+      if numericality = param.options[:numericality]
+        schema[:type] = numericality[:only_integer] || schema[: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]
+        schema[:exclusiveMaximum] = numericality[:less_than] if numericality[:less_than]
       end
 
       if param.options[:inclusion]
@@ -160,13 +166,12 @@ module ApiRegulator
 
       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]]
+          shared_schema = ApiRegulator.shared_schema(schema.options[:ref])
           raise "Shared schema not found for ref: #{schema.options[:ref]}" unless shared_schema
 
           responses[status_code.to_s] = {
@@ -177,6 +182,10 @@ module ApiRegulator
               }
             }
           }.compact
+        elsif schema.children.empty?
+          responses[status_code.to_s] = {
+            description: schema.desc.presence
+          }
         else
           responses[status_code.to_s] = {
             description: schema.desc.presence,
@@ -195,6 +204,31 @@ module ApiRegulator
       add_security_schemes(schema)
     end
 
+    def self.add_webhooks(schema)
+      return if ApiRegulator.webhook_definitions.empty?
+
+      schema[:webhooks] ||= {}
+      ApiRegulator.webhook_definitions.each do |webhook|
+        schema[:webhooks][webhook.event_name] = {
+          post: {
+            summary: webhook.title,
+            description: webhook.description.presence || webhook.title,
+            tags: webhook.tags,
+            requestBody: {
+              required: true,
+              content: {
+                'application/json' => {
+                  schema: expand_nested_params(webhook.params),
+                  examples: webhook.examples || {}
+                }
+              }
+            },
+            responses: generate_responses(webhook)
+          }.compact
+        }
+      end
+    end
+
     def self.add_shared_schemas(schema)
       return unless ApiRegulator.shared_schemas.present?
 

data/lib/api_regulator/param.rb

@@ -19,11 +19,20 @@ module ApiRegulator
       @children << child
     end
 
-    def ref(ref_name)
-      shared_schema = ApiRegulator.shared_schemas[ref_name]
+    def ref(ref_name, except: [], only: [])
+      shared_schema = ApiRegulator.shared_schema(ref_name)
       raise "Shared schema #{ref_name} not found" unless shared_schema
 
-      shared_schema.params.each do |shared_param|
+      # Filter parameters based on `only` or `except` options
+      filtered_params = shared_schema.params
+
+      if only.any?
+        filtered_params = filtered_params.select { |param| only.include?(param.name) }
+      elsif except.any?
+        filtered_params = filtered_params.reject { |param| except.include?(param.name) }
+      end
+
+      filtered_params.each do |shared_param|
         @children << shared_param
       end
     end

data/lib/api_regulator/security.rb

@@ -0,0 +1,13 @@
+module ApiRegulator
+  class << self
+    attr_accessor :security
+
+    def security_schemes
+      @security_schemes ||= {}
+    end
+
+    def security_schemes=(scheme)
+      @security_schemes = scheme
+    end
+  end
+end

data/lib/api_regulator/shared_schema.rb

@@ -15,23 +15,32 @@ module ApiRegulator
     end
   end
 
+  @shared_schemas = {}
+  @shared_schema_registry = {}
+
   class << self
-    attr_accessor :security
+    attr_accessor :shared_schema_registry
 
     def shared_schemas
-      @shared_schemas ||= {}
-    end
+      shared_schema_registry.each do |name, (description, block)|
+        @shared_schemas[name] = SharedSchema.new(name, description, &block)
+      end
 
-    def security_schemes
-      @security_schemes ||= {}
+      @shared_schemas
     end
 
-    def shared_schema(name, description, &block)
-      shared_schemas[name] = SharedSchema.new(name, description, &block)
+    def shared_schema(name)
+      if shared_schema_registry[name]
+        description, block = shared_schema_registry.delete(name)
+
+        @shared_schemas[name] = SharedSchema.new(name, description, &block)
+      end
+
+      @shared_schemas[name]
     end
 
-    def security_schemes=(scheme)
-      @security_schemes = scheme
+    def register_shared_schema(name, description, &block)
+      shared_schema_registry[name] = [description, block]
     end
   end
 end

data/lib/api_regulator/validator.rb

@@ -110,7 +110,7 @@ module ApiRegulator
       end
 
       raw_value.each_with_index do |value, index|
-        unless value.is_a?(Hash)
+        unless value.is_a?(Hash) || raw_value.is_a?(ActionController::Parameters)
           errors.add("#{attribute}[#{index}]", "must be a hash")
           next
         end
@@ -164,7 +164,8 @@ module ApiRegulator
         errors.add(attribute, "can't be blank") if param.options[:presence]
         return
       end
-      unless raw_value.is_a?(Hash)
+
+      unless raw_value.is_a?(Hash) || raw_value.is_a?(ActionController::Parameters)
         errors.add(attribute, "must be a hash")
         return
       end
@@ -231,6 +232,10 @@ module ApiRegulator
       end
     end
 
+    def self.reset_validators
+      @validators = {}
+    end
+
     def initialize(attributes = {})
       @raw_attributes = attributes.deep_symbolize_keys
       allowed_attributes = attributes.slice(*self.class.defined_attributes.map(&:to_sym))
@@ -238,8 +243,3 @@ module ApiRegulator
     end
   end
 end
-
-class FooValidator
-  include ActiveModel::Model
-  include ActiveModel::Attributes
-end

data/lib/api_regulator/version.rb

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

data/lib/api_regulator/webhook.rb

@@ -0,0 +1,59 @@
+module ApiRegulator
+  class Webhook
+    attr_reader :event_name, :description, :params, :responses, :examples, :tags, :title
+
+    def initialize(event_name, desc: nil, title: nil, tags: [], &block)
+      @event_name = event_name
+      @description = desc
+      @title = title
+      @tags = tags
+      @params = []
+      @responses = {}
+
+      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
+
+    def ref(ref_name, except: [], only: [])
+      shared_schema = ApiRegulator.shared_schema(ref_name)
+      raise "Shared schema #{ref_name} not found" unless shared_schema
+
+      # Filter parameters based on `only` or `except` options
+      filtered_params = shared_schema.params
+
+      if only.any?
+        filtered_params = filtered_params.select { |param| only.include?(param.name) }
+      elsif except.any?
+        filtered_params = filtered_params.reject { |param| except.include?(param.name) }
+      end
+
+      filtered_params.each do |shared_param|
+        @params << shared_param
+      end
+    end
+
+    def response(status_code, description, &block)
+      @responses[status_code] = Param.new(:root, :object, desc: description, &block)
+    end
+
+    def example(name, value, default: false)
+      @examples ||= {}
+      @examples[name] = { summary: "#{name} Example", value: value }
+      @default_example = value if default
+    end
+  end
+
+  class << self
+    def webhook_definitions
+      @webhook_definitions ||= []
+    end
+
+    def reset_webhook_definitions
+      @webhook_definitions = []
+    end
+  end
+end

data/lib/tasks/api_regulator_tasks.rake

@@ -1,10 +1,11 @@
+require 'yaml'
+
 namespace :api_docs do
   desc 'Generate OpenAPI schema'
   task generate: :environment do
-    Rails.application.eager_load!
+    Rails.application.eager_load! # Ensure all controllers and API definitions are loaded
 
-    api_definitions = ApiRegulator.configuration.base_controller_klass.descendants.flat_map(&:api_definitions)
-    ApiRegulator::OpenApiGenerator.generate(api_definitions)
+    ApiRegulator::OpenApiGenerator.generate(ApiRegulator.api_definitions)
   end
 
   desc "Upload OpenAPI schema to ReadMe"
@@ -16,10 +17,11 @@ namespace :api_docs do
     readme_api_endpoint = "https://dash.readme.com/api/v1/api-specification"
 
     # Read the OpenAPI schema file
-    unless File.exist?(ApiRegulator.configuration.docs_path)
-      raise "OpenAPI schema file not found at #{ApiRegulator.configuration.docs_path}"
+    schema_path = "#{ApiRegulator.configuration.docs_path}/openapi.json"
+    unless File.exist?(schema_path)
+      raise "OpenAPI schema file not found at #{schema_path}"
     end
-    openapi_content = File.read(ApiRegulator.configuration.docs_path)
+    openapi_content = File.read(schema_path)
 
     # Upload to ReadMe
     require 'net/http'
@@ -63,5 +65,134 @@ namespace :api_docs do
   task publish: :environment do
     Rake::Task["api_docs:generate"].invoke
     Rake::Task["api_docs:upload"].invoke
+    Rake::Task["api_docs:upload_pages"].invoke
+  end
+
+  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")
+    base_readme_api_endpoint = "https://dash.readme.com/api/v1/docs"
+
+    # Discover all documentation files
+    pages_directory = "#{ApiRegulator.configuration.docs_path}/**/*.md"
+    page_files = Dir.glob(pages_directory)
+
+    # Iterate through each file
+    page_files.each do |file_path|
+      # Extract metadata and body
+      metadata, body = parse_markdown_file(file_path)
+      raise "No metadata found in #{file_path}" unless metadata
+
+      # Use metadata to build the API request
+      slug = metadata["slug"] || File.basename(file_path, ".md").gsub("_", "-")
+      body = {
+        type: "basic",
+        categorySlug: "documentation",
+        hidden: false
+      }.merge(metadata)
+      body["slug"] ||= slug
+
+      raise("Title missing in #{file_path}") unless body["title"].present?
+
+      # Build the API request
+      if check_if_page_exists(slug)
+        uri = URI.parse("#{base_readme_api_endpoint}/#{slug}")
+        request = Net::HTTP::Put.new(uri)
+      else
+        uri = URI.parse("#{base_readme_api_endpoint}")
+        request = Net::HTTP::Post.new(uri)
+      end
+      request["Authorization"] = "Basic #{Base64.strict_encode64(readme_api_key)}"
+      request["Content-Type"] = "application/json"
+      request.body = body.compact.to_json
+
+      # Send the request
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+        http.request(request)
+      end
+
+      # Handle the response
+      case response.code.to_i
+      when 200
+        puts "Page '#{body["title"]}' successfully updated!"
+      when 201
+        puts "Page '#{body["title"]}' successfully created!"
+      else
+        puts "Failed to upload page '#{body["title"]}'!"
+        puts "Response Code: #{response.code}"
+        puts "Response Body: #{response.body}"
+      end
+    end
+  end
+
+  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_categories_api_endpoint = "https://dash.readme.com/api/v1/categories"
+
+    # Build the API request
+    uri = URI.parse(readme_categories_api_endpoint)
+    request = Net::HTTP::Get.new(uri)
+    request["Authorization"] = "Basic #{Base64.strict_encode64(readme_api_key)}"
+    request["Content-Type"] = "application/json"
+
+    # Send the request
+    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+      http.request(request)
+    end
+
+    # Handle the response
+    case response.code.to_i
+    when 200
+      puts "Categories"
+      pp JSON.parse(response.body)
+    else
+      puts "Failed to fetch categories"
+      puts "Response Code: #{response.code}"
+      puts "Response Body: #{response.body}"
+    end
+  end
+
+  def parse_markdown_file(file_path)
+    content = File.read(file_path)
+    metadata = nil
+    body = ""
+
+    # Split metadata and body
+    if content =~ /\A---\s*\n(.*?)\n---\s*\n(.*)/m
+      metadata = YAML.safe_load($1)
+      body = $2
+    else
+      raise "YAML front matter missing in #{file_path}"
+    end
+
+    [metadata, body]
+  end
+
+  def check_if_page_exists(slug)
+    readme_api_key = ENV['RDME_API_KEY'] || 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)}"
+    request["Content-Type"] = "application/json"
+
+    # Send the request
+    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+      http.request(request)
+    end
+
+    # Handle the response
+    case response.code.to_i
+    when 200
+      true
+    when 404
+      false
+    else
+      puts "Failed to serach for page"
+      puts "Response Code: #{response.code}"
+      puts "Response Body: #{response.body}"
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api-regulator
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Geoff Massanek
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-06 00:00:00.000000000 Z
+date: 2024-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -130,6 +130,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/spec.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
@@ -151,10 +152,12 @@ files:
 - lib/api_regulator/formats.rb
 - lib/api_regulator/open_api_generator.rb
 - lib/api_regulator/param.rb
+- lib/api_regulator/security.rb
 - lib/api_regulator/shared_schema.rb
 - lib/api_regulator/validation_error.rb
 - lib/api_regulator/validator.rb
 - lib/api_regulator/version.rb
+- lib/api_regulator/webhook.rb
 - lib/tasks/api_regulator_tasks.rake
 homepage: https://github.com/Stellarcred/stellar-gears
 licenses: