api-regulator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8474dc3c3898732b6e48a0b2c1722ecc13735e95474b01d9c4223be2cc461653
+  data.tar.gz: 541a39193368ff06b3932f869e75d27a50375ae5c2acd772e0276aa2c892bc8a
+SHA512:
+  metadata.gz: 67f74a784f20dc965e53a838c6ea8d068242cf77fd7aa7508c6e7e427efd4fef9f29a8242ab737f375b7accc84192551acc40036cfeb9778c1899731510cc102
+  data.tar.gz: 732b45b1592042bc7259f82d84b396583a74acb92daac22636d1edddc9f2b41771eea4226459b6709ac109b8ed430a6838ef76a592d2c2742d6ae5dcae3e2b36

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+spec/support/log/**
+spec/tmp
+
+api-regulator-*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+3.3.6

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.10
+before_install: gem install bundler -v 1.17.2

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in api-regulator.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,221 @@
+PATH
+  remote: .
+  specs:
+    api-regulator (0.1.0)
+      activemodel
+      activesupport
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.2.2)
+      actionpack (= 7.2.2)
+      activesupport (= 7.2.2)
+      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)
+      mail (>= 2.8.0)
+    actionmailer (7.2.2)
+      actionpack (= 7.2.2)
+      actionview (= 7.2.2)
+      activejob (= 7.2.2)
+      activesupport (= 7.2.2)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (7.2.2)
+      actionview (= 7.2.2)
+      activesupport (= 7.2.2)
+      nokogiri (>= 1.8.5)
+      racc
+      rack (>= 2.2.4, < 3.2)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      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)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.2.2)
+      activesupport (= 7.2.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (7.2.2)
+      activesupport (= 7.2.2)
+      globalid (>= 0.3.6)
+    activemodel (7.2.2)
+      activesupport (= 7.2.2)
+    activerecord (7.2.2)
+      activemodel (= 7.2.2)
+      activesupport (= 7.2.2)
+      timeout (>= 0.4.0)
+    activestorage (7.2.2)
+      actionpack (= 7.2.2)
+      activejob (= 7.2.2)
+      activerecord (= 7.2.2)
+      activesupport (= 7.2.2)
+      marcel (~> 1.0)
+    activesupport (7.2.2)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+    base64 (0.2.0)
+    benchmark (0.4.0)
+    bigdecimal (3.1.8)
+    builder (3.3.0)
+    byebug (11.1.3)
+    concurrent-ruby (1.3.4)
+    connection_pool (2.4.1)
+    crass (1.0.6)
+    date (3.4.0)
+    diff-lcs (1.5.1)
+    drb (2.2.1)
+    erubi (1.13.0)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.6)
+      concurrent-ruby (~> 1.0)
+    io-console (0.7.2)
+    irb (1.14.1)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    logger (1.6.1)
+    loofah (2.23.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.8)
+    minitest (5.25.2)
+    net-imap (0.5.1)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.0)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.16.8)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.16.8-arm64-darwin)
+      racc (~> 1.4)
+    psych (5.2.0)
+      stringio
+    racc (1.8.1)
+    rack (3.1.8)
+    rack-session (2.0.0)
+      rack (>= 3.0.0)
+    rack-test (2.1.0)
+      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)
+      bundler (>= 1.15.0)
+      railties (= 7.2.2)
+    rails-dom-testing (2.2.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.1)
+      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)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rake (13.2.1)
+    rdoc (6.8.1)
+      psych (>= 4.0.0)
+    reline (0.5.11)
+      io-console (~> 0.5)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-rails (5.1.2)
+      actionpack (>= 5.2)
+      activesupport (>= 5.2)
+      railties (>= 5.2)
+      rspec-core (~> 3.10)
+      rspec-expectations (~> 3.10)
+      rspec-mocks (~> 3.10)
+      rspec-support (~> 3.10)
+    rspec-support (3.13.1)
+    securerandom (0.3.2)
+    stringio (3.1.2)
+    thor (1.3.2)
+    timeout (0.4.2)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    useragent (0.16.10)
+    websocket-driver (0.7.6)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.1)
+
+PLATFORMS
+  arm64-darwin-23
+  ruby
+
+DEPENDENCIES
+  api-regulator!
+  bundler (~> 2.5)
+  byebug (= 11.1.3)
+  rails (~> 7.0)
+  rake (>= 12.3)
+  rspec (~> 3.0)
+  rspec-rails (~> 5.0)
+
+BUNDLED WITH
+   2.5.23

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Geoff Massanek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,154 @@
+# ApiRegulator
+
+ApiRegulator is a Ruby gem designed to **document** and **validate APIs** in Rails applications. It provides a clean DSL for defining API endpoints, parameter validations, and response schemas directly in your Rails controllers, while also generating OpenAPI 3.1.0-compliant documentation for tools like Swagger and ReadMe.
+
+ApiRegulator relies on **Active Model validations** for parameter validation, making it familiar and intuitive for Rails developers.
+
+## Features
+
+- **API Documentation DSL**:
+  Define API endpoints, request parameters, and response schemas in an intuitive, Rails-friendly DSL.
+  
+- **Dynamic Validation**:
+  Automatically validate incoming requests against the defined parameters using **Active Model validations**, reducing boilerplate code.
+
+- **OpenAPI Documentation**:
+  Generate fully compliant OpenAPI 3.1.0 JSON files, ready for use with documentation tools like Swagger or ReadMe.
+
+- **Reusability**:
+  Share common response schemas across multiple endpoints for DRY definitions.
+
+## ToDo
+- [ ] More tests
+  - [ ] Invalid Configurations (errors for invalid types)
+  - [ ] Empty Shared Schemas
+  - [ ] Custom Length and Numericality Options
+- [ ] Publish to rubygems
+- [ ] See if we're missing any other OpenAPI directives we could use
+  - [ ] nullable params
+- [ ] Handling of extra undocumented params
+- [ ] Set up CI / CD
+
+## Installation
+
+Add ApiRegulator to your Gemfile:
+
+```ruby
+gem 'api_regulator'
+```
+
+Run `bundle install` to install the gem.
+
+
+## Setup
+
+1. **Create an Initializer**:
+
+   Add the following to `config/initializers/api_regulator.rb`:
+
+   ```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.app_name = "My API" # shows in docs
+     config.rdme_api_id = ENV["RDME_API_ID"] # Optional: ReadMe API ID for schema uploads
+     config.servers = [
+       { url: "https://stg.example.com", description: "Staging", "x-default": true },
+       { url: "https://example.com", description: "Production" }
+     ]
+   end
+   ```
+
+2. **Include the DSL in Your Base Controller**:
+
+   Include the DSL and validation methods in your base API controller:
+
+   ```ruby
+   class Api::ApplicationController < ActionController::API
+     include ApiRegulator::DSL
+     include ApiRegulator::ControllerMixin
+   end
+   ```
+
+## Usage
+
+**Defining Endpoints**
+
+Use the DSL in your controllers to define API endpoints, request parameters, and response schemas.
+
+```ruby
+class Api::V1::CustomersController < Api::ApplicationController
+  api self, :create, "Enroll a customer" do
+    param :customer, presence: true do
+      param :first_name, :string, presence: true
+      param :last_name, :string, presence: true
+      param :email, :string, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+      param :ssn, :string, presence: true, length: { minimum: 9, maximum: 9 }
+    end
+
+    response 200, "Customer successfully enrolled" do
+      param :customer do
+        param :id, :string, desc: "Customer ID"
+        param :email, :string, desc: "Customer email"
+      end
+    end
+
+    response 422, ref: :validation_errors
+  end
+
+  def create
+    validate_params! # Validate request params against the DSL definition
+
+    customer = Customer.create!(api_params[:customer]) # Use dynamically generated params
+    render json: customer, status: :ok
+  end
+end
+```
+
+## Shared Schemas
+
+Define reusable schemas for common responses in your initializer:
+
+```ruby
+ApiRegulator.shared_schema :validation_errors, "Validation error response" do
+  param :errors, :array, desc: "Array of validation errors", items_type: :string
+end
+```
+
+Reference the shared schema in your responses:
+```ruby
+  response 422, ref: :validation_errors
+end
+```
+
+## Generating OpenAPI Documentation
+
+Generate OpenAPI documentation using the provided Rake tasks:
+
+
+1. **Generate the Schema:**
+   ```bash
+   rake api_docs:generate
+   ```
+
+2. **Upload to ReadMe (Optional)**:
+   ```bash
+   rake api_docs:upload
+   ```
+   This uploads the OpenAPI file to ReadMe. Ensure you’ve configured the RDME_API_KEY and optional RDME_API_ID.
+
+3. **Publish Both**:
+   ```bash
+   rake api_docs:publish
+   ```
+
+## Contributing
+1. Fork the repository.
+2. Create your feature branch (git checkout -b feature/new-feature).
+3. Commit your changes (git commit -am 'Add some feature').
+4. Push to the branch (git push origin feature/new-feature).
+5. Open a pull request.
+
+## License
+This gem is available as open-source software under the [MIT License](https://mit-license.org/).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/api-regulator.gemspec

@@ -0,0 +1,48 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "api_regulator/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "api-regulator"
+  spec.version       = ApiRegulator::VERSION
+  spec.authors       = ["Geoff Massanek"]
+  spec.email         = ["geoff@stellarfi.com"]
+
+  spec.summary       = %q{Define, document, and validate your Rails APIs}
+  spec.description   = %q{Define your Rails APIs with a clean, familiar DSL. Validate them with ActiveModel-like validations. Generate OpenAPI documentation.}
+  spec.homepage      = "https://github.com/Stellarcred/stellar-gears"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/Stellarcred/stellar-gears"
+    spec.metadata["changelog_uri"] = "https://github.com/Stellarcred/stellar-gears"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "activesupport"
+  spec.add_runtime_dependency "activemodel"
+
+  spec.add_development_dependency "bundler", "~> 2.5"
+  spec.add_development_dependency "rake", ">= 12.3"
+  spec.add_development_dependency "rails", "~> 7.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec-rails", "~> 5.0"
+  spec.add_development_dependency "byebug", "11.1.3"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/api-regulator.rb

@@ -0,0 +1,35 @@
+require_relative 'api_regulator/api'
+require_relative 'api_regulator/configuration'
+require_relative 'api_regulator/controller_mixin'
+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/shared_schema'
+require_relative 'api_regulator/validation_error'
+require_relative 'api_regulator/validator'
+require_relative 'api_regulator/version'
+
+# Load tasks if Rails is present
+if defined?(Rake)
+  load 'tasks/api_regulator_tasks.rake'
+end
+
+module ApiRegulator
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    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)
+    end
+  end
+end

data/lib/api_regulator/api.rb

@@ -0,0 +1,82 @@
+module ApiRegulator
+  class Api
+    attr_reader :controller_class, :controller_path, :controller_name, :action_name, :description, :params, :responses
+
+    def initialize(controller_class, action_name, description, &block)
+      @controller_class = controller_class
+      @controller_name = controller_class.name
+      @controller_path = controller_class.controller_path
+      @action_name = action_name.to_s
+      @description = description
+
+      @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)
+      shared_schema = ApiRegulator.shared_schemas[ref_name]
+      raise "Shared schema #{ref_name} not found" unless shared_schema
+
+      shared_schema.params.each do |shared_param|
+        @params << shared_param
+      end
+    end
+
+    def response(status_code, description_or_options, &block)
+      if description_or_options.is_a?(Hash) && description_or_options[:ref]
+        # Reference to a shared schema
+        @responses[status_code] = Param.new(:root, :object, ref: description_or_options[:ref], &block)
+      else
+        # Inline schema definition
+        schema = Param.new(:root, :object, desc: description_or_options, &block)
+        @responses[status_code] = schema
+      end
+    end
+
+    def path
+      rails_route.path.spec.to_s
+        .sub("(.:format)", "")   # Remove optional format
+        .gsub(/:([\w_]+)/, '{\1}') # Replace `:param` with `{param}`
+    end
+
+    def http_method
+      rails_route.verb&.downcase
+    end
+
+    def rails_route
+      route = Rails.application.routes.routes.find do |r|
+        r.defaults[:controller] == controller_path &&
+        r.defaults[:action] == action_name
+      end
+
+      raise "HTTP method not found for #{controller_name}##{action_name}" unless route
+
+      route
+    end
+
+    def operation_id
+      "#{controller_path.gsub("/", "-")}-#{action_name}"
+    end
+
+    def tags
+      [
+        controller_name
+          .demodulize
+          .sub("Controller", "")
+          .underscore
+          .humanize
+      ]
+    end
+
+    def allows_body?
+      http_method != "get"
+    end
+  end
+end

data/lib/api_regulator/configuration.rb

@@ -0,0 +1,18 @@
+module ApiRegulator
+  class Configuration
+    attr_accessor :base_controller, :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"
+      @servers = []
+    end
+
+    def base_controller_klass
+      ApiRegulator.configuration.base_controller.constantize
+    end
+  end
+end