api-regulator 0.1.19 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2222bdbbc060773ad1c512bfdedd9f7b7acee3920249223236e4468317520353
-  data.tar.gz: 3642bc547ab2ddde180ab34b551d42e496fcc1e49bda947b1f0f9f521a79d498
+  metadata.gz: 712a8be4e5ef4c7528a09aa3f7370f2e5f8024ae15954066ac52663a0c4b5958
+  data.tar.gz: '09e89ba29c1a970bdedcc1a266ae045b2435dd6f5fb8f1ad66c84cae3007aae1'
 SHA512:
-  metadata.gz: 22a0cb6db6778f6fdbe0cc795658628120c57907a513c73bdd52f3d138135d8895b1044931e9392e67e265bf5e112b22003837c924d56717f5043494a68401e0
-  data.tar.gz: e728660a393d6f57028fa26732b160c94bcc7e7567bc6957fa0d55322de4cfac490c4a742136c53f1119df79bd5d6ea088d393fcc363115e91734b7e858adac4
+  metadata.gz: 340219f8c1b4ee3e5bf6c7fe0889ef32f0056f87615a8b4beea9bca235667f2310bc9d0d510a15982ce78d7b79281449c26bb09dc5839f549fdbb2e7d32fb9cf
+  data.tar.gz: 0d9a361b19a8922cf927a06c66abbf5007e08f790af02c9d30154f9bfa97316e98672fd12d6786374a4660f88b4e8426539b7e1114a2b8d72eced0c9f907e197

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    api-regulator (0.1.19)
+    api-regulator (0.1.21)
       activemodel (~> 8.0)
       activesupport (~> 8.0)
 

data/README.md

@@ -43,7 +43,14 @@ Run `bundle install` to install the gem.
      config.api_base_url = "/api/v1" # Set a common base path for your API endpoints
      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
+
+     # Optional: ReadMe versions and API ID for schema uploads
+     config.versions = {
+       "v1.0" => "abc123",
+       "v1.0-internal" => "abc345"
+     }
+     config.default_version = "v1.0-internal"
+
      config.servers = [
        { url: "https://stg.example.com", description: "Staging", "x-default": true },
        { url: "https://example.com", description: "Production" }
@@ -120,7 +127,8 @@ Generate OpenAPI documentation using the provided Rake tasks:
 
 1. **Generate the Schema:**
    ```bash
-   rake api_docs:generate
+   rake api_docs:generate # uses default (or no) version
+   VERSION=v1.0-internal rake api_docs:generate # specifies the to generate
    ```
 
 2. **Upload to ReadMe (Optional)**:

data/lib/api_regulator/api.rb

@@ -1,14 +1,15 @@
 module ApiRegulator
   class Api
-    attr_reader :controller_class, :controller_path, :controller_name, :action_name, :description, :title, :params, :responses
+    attr_reader :controller_class, :controller_path, :controller_name, :action_name, :description, :title, :params, :responses, :versions
 
-    def initialize(controller_class, action_name, desc: nil, title: nil, &block)
+    def initialize(controller_class, action_name, desc: nil, title: nil, versions: [], &block)
       @controller_class = controller_class
       @controller_name = controller_class.name
       @controller_path = controller_class.controller_path
       @action_name = action_name.to_s
       @description = desc
       @title = title
+      @versions = Array(versions).map(&:to_sym)
 
       @params = []
       @responses = {}
@@ -16,9 +17,9 @@ module ApiRegulator
       instance_eval(&block) if block_given?
     end
 
-    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
+    def param(name, type = nil, **options, &block)
+      options[:api] ||= self
+      @params << Param.new(name, type, **options, &block)
     end
 
     def ref(ref_name, except: [], only: [])
@@ -90,6 +91,12 @@ module ApiRegulator
       ]
     end
 
+    def for_version?(version)
+      return true unless versions.present? && version.present?
+
+      versions.include?(version.to_sym)
+    end
+
     def allows_body?
       http_method != "get"
     end

data/lib/api_regulator/configuration.rb

@@ -1,6 +1,6 @@
 module ApiRegulator
   class Configuration
-    attr_accessor :api_base_url, :app_name, :docs_path, :rdme_api_id, :servers
+    attr_accessor :api_base_url, :app_name, :docs_path, :versions, :default_version, :servers
 
     def initialize
       # Set default values

data/lib/api_regulator/dsl.rb

@@ -9,7 +9,7 @@ module ApiRegulator
     end
 
     module ClassMethods
-      def api(controller_class, action, desc: nil, title: nil, &block)
+      def api(controller_class, action, desc: nil, title: nil, versions: [], &block)
         @api_definitions ||= []
 
         api_definition = Api.new(
@@ -17,6 +17,7 @@ module ApiRegulator
           action.to_s,
           desc: desc,
           title: title,
+          versions: versions,
           &block
         )
 

data/lib/api_regulator/open_api_generator.rb

@@ -2,35 +2,60 @@ require 'json'
 
 module ApiRegulator
   class OpenApiGenerator
-    def self.generate(api_definitions)
-      schema = {
+    def self.generate(api_definitions, version: ApiRegulator.configuration.default_version)
+      generator = new(api_definitions, version: version)
+      generator.generate
+    end
+
+    def self.schema_file_path(version: ApiRegulator.configuration.default_version)
+      file_name = version.present? ? "openapi-#{version}.json" : "openapi.json"
+      [
+        ApiRegulator.configuration.docs_path,
+        "/",
+        file_name
+      ].compact.join
+    end
+
+    attr_reader :api_definitions
+    attr_reader :version
+    attr_reader :final_schema
+
+    def initialize(api_definitions, version:)
+      @api_definitions = api_definitions
+      @version = version
+    end
+
+    def generate
+      @final_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: {}
       }
+      final_schema[:info][:version] = version if version.present?
 
-      add_components(schema)
-      add_security(schema)
-      add_webhooks(schema)
+      add_components
+      add_security
+      add_webhooks
 
       api_definitions.each do |api|
-        add_api_to_schema(schema, api)
+        add_api_to_schema(api)
       end
 
-      schema_path = "#{ApiRegulator.configuration.docs_path}/openapi.json"
-      File.write(schema_path, JSON.pretty_generate(schema))
+      schema_path = self.class.schema_file_path(version: version)
+      File.write(schema_path, JSON.pretty_generate(final_schema))
       puts "OpenAPI schema generated: #{schema_path}"
     end
 
     private
 
-    def self.add_api_to_schema(schema, api)
-      schema[:paths][api.path] ||= {}
+    def add_api_to_schema(api)
+      return unless api.for_version?(version)
+
+      final_schema[:paths][api.path] ||= {}
       data = {
         summary: api.title,
         description: api.description.presence || api.title,
@@ -43,10 +68,10 @@ module ApiRegulator
       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
+      final_schema[:paths][api.path][api.http_method] = data
     end
 
-    def self.generate_request_body(api)
+    def generate_request_body(api)
       params = api.params.select(&:body?)
       return {} if params.empty?
 
@@ -60,7 +85,7 @@ module ApiRegulator
       }
     end
 
-    def self.expand_nested_params(params)
+    def expand_nested_params(params)
       schema = {
         type: 'object',
         properties: {},
@@ -68,6 +93,8 @@ module ApiRegulator
       }
 
       params.each do |param|
+        next unless param.for_version?(version)
+
         schema[:properties][param.name] =
           if param.type == :array
             generate_array_schema(param)
@@ -86,7 +113,7 @@ module ApiRegulator
       schema
     end
 
-    def self.generate_array_schema(param)
+    def generate_array_schema(param)
       item_schema = param.children.any? ? generate_object_schema(param) : { type: param.item_type }
 
       {
@@ -96,24 +123,26 @@ module ApiRegulator
       }.compact
     end
 
-    def self.generate_object_schema(param)
+    def 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
 
-    def self.generate_parameters(api)
-      api.params.select(&:parameter?).map do |p|
-        generate_param_schema(p)
+    def generate_parameters(api)
+      api.params.select(&:parameter?).filter_map do |param|
+        next unless param.for_version?(version)
+
+        generate_param_schema(param)
           .merge({
-            name: p.name,
-            required: p.location == :path || p.required? || false
+            name: param.name,
+            required: param.path? || param.required? || false
           })
       end
     end
 
-    def self.generate_param_schema(param)
+    def generate_param_schema(param)
       schema = {}
 
       schema[:description] = param.desc if param.desc.present?
@@ -136,7 +165,7 @@ module ApiRegulator
       schema
     end
 
-    def self.generate_param_schema_details(param, schema)
+    def generate_param_schema_details(param, schema)
       # Add length constraints
       if param.options[:length]
         schema[:minLength] = param.options[:length][:minimum] if param.options[:length][:minimum]
@@ -178,7 +207,7 @@ module ApiRegulator
 
     end
 
-    def self.generate_responses(api)
+    def generate_responses(api)
       Hash[api.responses.sort].each_with_object({}) do |(status_code, schema), responses|
         if schema.options[:ref]
           shared_schema = ApiRegulator.shared_schema(schema.options[:ref])
@@ -209,17 +238,17 @@ module ApiRegulator
       end
     end
 
-    def self.add_components(schema)
-      add_shared_schemas(schema)
-      add_security_schemes(schema)
+    def add_components
+      add_shared_schemas
+      add_security_schemes
     end
 
-    def self.add_webhooks(schema)
+    def add_webhooks
       return if ApiRegulator.webhook_definitions.empty?
 
-      schema[:webhooks] ||= {}
+      final_schema[:webhooks] ||= {}
       ApiRegulator.webhook_definitions.each do |webhook|
-        schema[:webhooks][webhook.event_name] = {
+        final_schema[:webhooks][webhook.event_name] = {
           post: {
             summary: webhook.title,
             description: webhook.description.presence || webhook.title,
@@ -239,30 +268,30 @@ module ApiRegulator
       end
     end
 
-    def self.add_shared_schemas(schema)
+    def add_shared_schemas
       return unless ApiRegulator.shared_schemas.present?
 
-      schema[:components] ||= {}
-      schema[:components][:schemas] ||= {}
+      final_schema[:components] ||= {}
+      final_schema[:components][:schemas] ||= {}
 
       ApiRegulator.shared_schemas.each do |name, shared_schema|
-        schema[:components][:schemas][name] = expand_nested_params(shared_schema.params).merge(
+        final_schema[:components][:schemas][name] = expand_nested_params(shared_schema.params).merge(
           description: shared_schema.description
         ).compact
       end
     end
 
-    def self.add_security_schemes(schema)
+    def add_security_schemes
       return unless ApiRegulator.security_schemes.present?
 
-      schema[:components] ||= {}
-      schema[:components][:securitySchemes] = ApiRegulator.security_schemes
+      final_schema[:components] ||= {}
+      final_schema[:components][:securitySchemes] = ApiRegulator.security_schemes
     end
 
-    def self.add_security(schema)
+    def add_security
       return unless ApiRegulator.security.present?
 
-      schema[:security] = ApiRegulator.security
+      final_schema[:security] = ApiRegulator.security
     end
   end
 end

data/lib/api_regulator/param.rb

@@ -1,24 +1,27 @@
 module ApiRegulator
   class Param
-    attr_reader :name, :type, :options, :item_type, :desc, :location, :children, :api, :allow_arbitrary_keys
+    attr_reader :name, :type, :options, :item_type, :desc, :location, :children, :api, :allow_arbitrary_keys, :versions
 
-    def initialize(name, type = nil, item_type: nil, desc: "", location: :body, api: nil, allow_arbitrary_keys: false, **options, &block)
+    def initialize(name, type = nil, **options, &block)
       @name = name
       @type = type&.to_sym || (block_given? ? :object : :string)
-      @item_type = item_type
-      @location = location.to_sym
-      @desc = desc
-      @options = options
+
+      @item_type = options.delete(:item_type)
+      @desc = options.delete(:desc) || ""
+      @location = (options.delete(:location) || :body).to_sym
+      @api = options.delete(:api)
+      @allow_arbitrary_keys = options.delete(:allow_arbitrary_keys) || false
+      @versions = Array(options.delete(:versions)).map(&:to_sym)
+
       @children = []
-      @api = api
-      @allow_arbitrary_keys = allow_arbitrary_keys
+      @options = options
 
       instance_eval(&block) if block_given?
     end
 
-    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
+    def param(name, type = nil, **options, &block)
+      options[:api] ||= api
+      @children << Param.new(name, type, **options, &block)
     end
 
     def ref(ref_name, except: [], only: [])
@@ -111,6 +114,12 @@ module ApiRegulator
       end
     end
 
+    def for_version?(version)
+      return true unless versions.present? && version.present?
+
+      versions.include?(version.to_sym)
+    end
+
     def body?
       location == :body
     end

data/lib/api_regulator/shared_schema.rb

@@ -10,9 +10,8 @@ module ApiRegulator
       instance_eval(&block) if block_given?
     end
 
-    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
+    def param(name, type = nil, **options, &block)
+      @params << Param.new(name, type, **options, &block)
     end
 
     def response(status_code, description_or_options, &block)

data/lib/api_regulator/version.rb

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

data/lib/api_regulator/webhook.rb

@@ -13,9 +13,8 @@ module ApiRegulator
       instance_eval(&block) if block_given?
     end
 
-    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
+    def param(name, type = nil, **options, &block)
+      @params << Param.new(name, type, **options, &block)
     end
 
     def ref(ref_name, except: [], only: [])

data/lib/tasks/api_regulator_tasks.rake

@@ -5,22 +5,35 @@ namespace :api_docs do
   task generate: :environment do
     # Set an empty api key if none is provided
     ENV['RDME_API_KEY'] ||= ''
+    version = ENV['VERSION'] || ApiRegulator.configuration.default_version
 
     Rails.application.eager_load! # Ensure all controllers and API definitions are loaded
 
-    ApiRegulator::OpenApiGenerator.generate(ApiRegulator.api_definitions)
+    ApiRegulator::OpenApiGenerator.generate(ApiRegulator.api_definitions, version: version.presence)
+  end
+
+  desc 'Generate OpenAPI schemas for all versions'
+  task generate_all: :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.configuration.versions.keys.each do |version|
+      ApiRegulator::OpenApiGenerator.generate(ApiRegulator.api_definitions, version: version)
+    end
   end
 
   desc "Upload OpenAPI schema to ReadMe"
   task :upload => :environment do
     # ReadMe API key and version
     readme_api_key = ENV['RDME_API_KEY'].presence || raise("RDME_API_KEY is not set")
+    version = ENV['VERSION'] || ApiRegulator.configuration.default_version
 
     # ReadMe API endpoint
     readme_api_endpoint = "https://dash.readme.com/api/v1/api-specification"
 
     # Read the OpenAPI schema file
-    schema_path = "#{ApiRegulator.configuration.docs_path}/openapi.json"
+    schema_path =  ApiRegulator::OpenApiGenerator.schema_file_path(version: version)
     unless File.exist?(schema_path)
       raise "OpenAPI schema file not found at #{schema_path}"
     end
@@ -31,8 +44,8 @@ namespace :api_docs do
     require 'uri'
     require 'json'
 
-    if ApiRegulator.configuration.rdme_api_id
-      uri = URI.parse("#{readme_api_endpoint}/#{ApiRegulator.configuration.rdme_api_id}")
+    if version.present?
+      uri = URI.parse("#{readme_api_endpoint}/#{ApiRegulator.configuration.versions[version]}")
       request = Net::HTTP::Put.new(uri)
     else
       uri = URI.parse(readme_api_endpoint)
@@ -40,6 +53,7 @@ namespace :api_docs do
     end
     request["Authorization"] = "Basic #{Base64.strict_encode64(readme_api_key)}"
     request["Content-Type"] = "application/json"
+    request["x-readme-version"] = version if version.present?
     request.body = {
       spec: JSON.parse(openapi_content)
     }.to_json
@@ -54,7 +68,9 @@ namespace :api_docs do
       puts "OpenAPI schema successfully created!"
       puts "To use this for future publishing, add this to your ApiRegulator configs:"
       puts ""
-      puts "  config.rdme_api_id = \"#{JSON.parse(response.body)["_id"]}\""
+      puts "  config.versions = {"
+      puts "    \"<versionNumber>\": \"#{JSON.parse(response.body)["_id"]}\""
+      puts "  }"
       puts ""
     else
       puts "Failed to upload OpenAPI schema to ReadMe!"
@@ -75,6 +91,7 @@ namespace :api_docs do
   task :upload_pages => :environment do
     # Configuration
     readme_api_key = ENV['RDME_API_KEY'].presence || raise("RDME_API_KEY is not set")
+    version = ENV['VERSION'] || ApiRegulator.configuration.default_version
     base_readme_api_endpoint = "https://dash.readme.com/api/v1/docs"
 
     # Discover all documentation files
@@ -109,6 +126,7 @@ namespace :api_docs do
       end
       request["Authorization"] = "Basic #{Base64.strict_encode64(readme_api_key)}"
       request["Content-Type"] = "application/json"
+      request["x-readme-version"] = version if version.present?
       request.body = request_body.compact.to_json
 
       # Send the request
@@ -134,6 +152,7 @@ namespace :api_docs do
   task :fetch_categories => :environment do
     # Configuration
     readme_api_key = ENV['RDME_API_KEY'].presence || raise("RDME_API_KEY is not set")
+    version = ENV['VERSION'] || ApiRegulator.configuration.default_version
     readme_categories_api_endpoint = "https://dash.readme.com/api/v1/categories"
 
     # Build the API request
@@ -141,6 +160,7 @@ namespace :api_docs do
     request = Net::HTTP::Get.new(uri)
     request["Authorization"] = "Basic #{Base64.strict_encode64(readme_api_key)}"
     request["Content-Type"] = "application/json"
+    request["x-readme-version"] = version if version.present?
 
     # Send the request
     response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
@@ -177,10 +197,12 @@ namespace :api_docs do
 
   def check_if_page_exists(slug)
     readme_api_key = ENV['RDME_API_KEY'].presence || raise("RDME_API_KEY is not set")
+    version = ENV['VERSION'] || ApiRegulator.configuration.default_version
     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"
+    request["x-readme-version"] = version if version.present?
 
     # Send the request
     response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|

metadata

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