api-regulator 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88bc51a665a125169fea48c149623cfc72df75a4996685ea847ef84c83819aec
-  data.tar.gz: 1d61290605b37dd3c5a2b3b48d52490bbe5d1b993713f6d4386cfb7aedda3f21
+  metadata.gz: 805a7ee5772352ec9d9f1e8bea5f6f79ef5dd67c170bfb3ca62898a2685a0067
+  data.tar.gz: 75d36c102ed4f9494cfb8f97be7cca09de8206006fb1ca28352734f15ecc29d1
 SHA512:
-  metadata.gz: 7a3b2f318a78aa7c171faf82b7b24e1ede15a7a7d2a447f308f56b8aafe7c32da3ae611ed0303ac79013cef7355c82988c02dc5ed24cd9928bd9bb17fcef9c84
-  data.tar.gz: 82f9714a67fb41d91b65086e2fadd379cf04ea1516e93d853730a4c4be7bc663730cf8bdece2338c9931c3eb66fa8944cc2d436479f1d26cdfaa81645309ca87
+  metadata.gz: 45f235550878457b9af59dc1f3d4d2b70ac8afe581dfc35d9f5a13a37da67eb17ef9f6e4da1d877352eca27229847367909645f66d20cdaa807d9c52f133c894
+  data.tar.gz: a67c9b219a20a6e9dffd99fa33f285222452621b99c7304ffd3e7366f86fb8046505857c27047a86161bf3232cf07b81e35a75a7375fe7bace8a0708982ba9c1

data/.gitignore

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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    api-regulator (0.1.0)
+    api-regulator (0.1.2)
       activemodel
       activesupport
 

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

@@ -232,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))
@@ -239,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.1"
+  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.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Geoff Massanek
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-13 00:00:00.000000000 Z
+date: 2024-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -152,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: