api-regulator 0.1.27 → 0.1.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1930002f6e2b1b916f44c2aaf447b624c373f5393297d7aa12b665063ec75a56
-  data.tar.gz: f98dc9238b359bf019eeffe6f0f5a3a0dc001f8f8af91d80ba042828621cd699
+  metadata.gz: a4adbf41faf31da6c2dfd0ac4fa34753b1b145e4a54fe150716b248c0bb2ca8f
+  data.tar.gz: 3bf906b1cc68f8729c8593fda4af679525999b6d4ed27f8036b96a9b4a90466a
 SHA512:
-  metadata.gz: effb1e8e1cac07f20aa41dd4398b146afa13a59769c687bfc740730ae3a9bf7a84d81805dc11e0a0073c97c3375689d6d78647bef7cc1543ede8c065c1956474
-  data.tar.gz: a951dc617505560736c62a34aa4eae3d2c99364a39953ee64d337c232b516f9949d1cf90de9859d9d9b33c2036f42fc9421ea7ceabdf5ae81099b4f4bc9b8675
+  metadata.gz: 92cf6b80afec1af5113edb3ac6dfd64211931a3c47ade5b5aad032ed6c35343357cc158eebe7e5a27fb4a65ca600584bb64cbfaf36eb6532ebd721c98588157d
+  data.tar.gz: 1a5e008679121223946897c93b2a89efd1be92c267b4b5ffb07e484c35938236f842ba1fd2e9eea9c5de60bc1a5e931a95f207e348abe4062fde7a4f2d6a1227

data/Gemfile.lock

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

data/README.md

@@ -1,25 +1,21 @@
 # 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 is a Ruby gem designed to **document**, **validate**, and **generate OpenAPI schemas** for Rails APIs. It provides a clean, Rails-friendly DSL for defining API endpoints, parameter validations, response schemas, and webhook definitions directly in your controllers, while automatically generating OpenAPI 3.1.0-compliant documentation.
 
-ApiRegulator relies on **Active Model validations** for parameter validation, making it familiar and intuitive for Rails developers.
+ApiRegulator leverages **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
-- [ ] Handling of extra undocumented params
+- **🎯 API Documentation DSL**: Define API endpoints, request parameters, and response schemas using an intuitive, Rails-friendly DSL
+- **✅ Dynamic Request Validation**: Automatically validate incoming requests against defined parameters using Active Model validations
+- **📖 OpenAPI 3.1.0 Generation**: Generate fully compliant OpenAPI documentation ready for Swagger, Postman, or ReadMe
+- **🔗 Webhook Documentation**: Define and document webhook payloads with the same DSL
+- **🏷️ API Versioning**: Support multiple API versions with selective parameter inclusion
+- **🔒 Security Schemes**: Define authentication and authorization schemes
+- **🔄 Shared Schemas**: Reuse common response and parameter schemas across multiple endpoints
+- **📚 ReadMe Integration**: Built-in tasks for uploading documentation to ReadMe.com
+- **🛡️ Parameter Validation**: Strict validation with helpful error messages for unexpected parameters
+- **📄 Custom Page Management**: Upload and manage documentation pages alongside API specs
 
 ## Installation
 
@@ -31,131 +27,523 @@ gem 'api_regulator'
 
 Run `bundle install` to install the gem.
 
-
 ## Setup
 
-1. **Create an Initializer**:
-
-   Add the following to `config/initializers/api_regulator.rb`:
+### 1. Create an Initializer
 
-   ```ruby
-   ApiRegulator.configure do |config|
-     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
+Add the following to `config/initializers/api_regulator.rb`:
 
-     # Optional: ReadMe versions and API ID for schema uploads
-     config.versions = {
-       "v1.0" => "abc123",
-       "v1.0-internal" => "abc345"
-     }
-     config.default_version = "v1.0-internal"
+```ruby
+ApiRegulator.configure do |config|
+  config.api_base_url = "/api/v1"
+  config.docs_path = Rails.root.join("doc").to_s
+  config.app_name = "My API"
+
+  # Optional: Configure multiple API versions
+  config.versions = {
+    "v1.0" => "abc123",           # ReadMe API spec ID
+    "v1.0-internal" => "abc345"   # Internal version
+  }
+  config.default_version = "v1.0-internal"
+
+  # Optional: Define API servers
+  config.servers = [
+    { url: "https://stg.example.com", description: "Staging", "x-default": true },
+    { url: "https://example.com", description: "Production" }
+  ]
+end
+```
 
-     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
 
-2. **Include the DSL in Your Base Controller**:
+```ruby
+class Api::ApplicationController < ActionController::API
+  include ApiRegulator::DSL
+  include ApiRegulator::ControllerMixin
+end
+```
 
-   Include the DSL and validation methods in your base API controller:
+### 3. Define Security Schemes (Optional)
 
-   ```ruby
-   class Api::ApplicationController < ActionController::API
-     include ApiRegulator::DSL
-     include ApiRegulator::ControllerMixin
-   end
-   ```
+```ruby
+# In your initializer
+ApiRegulator.security_schemes = {
+  bearer_auth: {
+    type: "http",
+    scheme: "bearer",
+    bearerFormat: "JWT"
+  },
+  api_key: {
+    type: "apiKey",
+    in: "header",
+    name: "X-API-Key"
+  }
+}
+```
 
 ## Usage
 
-**Defining Endpoints**
-
-Use the DSL in your controllers to define API endpoints, request parameters, and response schemas.
+### Basic API Definition
 
 ```ruby
 class Api::V1::CustomersController < Api::ApplicationController
-  api self, :create, "Enroll a customer" do
+  api self, :create, desc: "Create a new customer", title: "Create Customer" do
+    # Path parameters
+    param :organization_id, :string, location: :path, presence: true
+
+    # Query parameters  
+    param :expand, :string, location: :query, desc: "Comma-separated list of fields to expand"
+
+    # Body parameters
     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 }
+      param :email, :string, presence: true, format: { with: ApiRegulator::Formats::EMAIL }
+      param :ssn, :string, presence: true, length: { is: 9 }
+      param :date_of_birth, :string, format: { with: ApiRegulator::Formats::DATE }
+      
+      # Nested objects
+      param :address, :object do
+        param :street, :string, presence: true
+        param :city, :string, presence: true
+        param :state, :string, presence: true, length: { is: 2 }
+        param :zip_code, :string, format: { with: ApiRegulator::Formats::ZIP_CODE }
+      end
+
+      # Arrays
+      param :phone_numbers, :array, item_type: :string
+      param :emergency_contacts, :array do
+        param :name, :string, presence: true
+        param :relationship, :string, presence: true
+        param :phone, :string, presence: true
+      end
     end
 
-    response 200, "Customer successfully enrolled" do
+    # Response definitions
+    response 201, "Customer successfully created" do
       param :customer do
-        param :id, :string, desc: "Customer ID"
-        param :email, :string, desc: "Customer email"
+        param :id, :string, desc: "Customer UUID"
+        param :email, :string, desc: "Customer email address"
+        param :created_at, :string, desc: "ISO 8601 timestamp"
       end
     end
 
     response 422, ref: :validation_errors
+    response 401, ref: :unauthorized_error
   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
+    validate_params! # Validates against DSL definition
+    
+    customer = Customer.create!(api_params[:customer])
+    render json: { customer: customer }, status: :created
   end
 end
 ```
 
-## Shared Schemas
+### Advanced Parameter Options
+
+#### Conditional Requirements
+
+```ruby
+param :ssn, :string, presence: { 
+  required_on: [:create, :update],           # Required only for these actions
+  required_except_on: [:show]                # Required except for these actions
+}
+```
 
-Define reusable schemas for common responses in your initializer:
+#### Version-Specific Parameters
 
 ```ruby
+param :legacy_field, :string, versions: [:v1], desc: "Only available in v1"
+param :new_feature, :boolean, versions: [:v2, :v3], desc: "Available in v2 and v3"
+```
+
+#### Type Validation and Formatting
+
+```ruby
+param :age, :integer, numericality: { greater_than: 0, less_than: 150 }
+param :website, :string, format: { with: ApiRegulator::Formats::URI }
+param :score, :number, numericality: { greater_than_or_equal_to: 0.0, less_than_or_equal_to: 100.0 }
+param :is_active, :boolean
+param :tags, :array, item_type: :string, inclusion: { in: ["vip", "standard", "premium"] }
+```
+
+#### Arbitrary Keys Support
+
+```ruby
+param :metadata, :object, allow_arbitrary_keys: true do
+  param :created_by, :string  # Known fields can still be defined
+end
+```
+
+#### Nullable Fields
+
+```ruby
+param :middle_name, :string, presence: { allow_nil: true }
+param :optional_date, :string, format: { with: ApiRegulator::Formats::DATE, allow_nil: true }
+```
+
+### Shared Schemas
+
+Define reusable schemas in your initializer:
+
+```ruby
+# Common error responses
 ApiRegulator.register_shared_schema :validation_errors, "Validation error response" do
-  param :errors, :array, desc: "Array of validation errors", items_type: :string
+  param :errors, :array, desc: "Array of validation error messages" do
+    param :field, :string, desc: "Field name that failed validation"
+    param :message, :string, desc: "Human-readable error message"
+    param :code, :string, desc: "Error code for programmatic handling"
+  end
+end
+
+ApiRegulator.register_shared_schema :unauthorized_error, "Authentication required" do
+  param :error, :string, desc: "Error message"
+  param :code, :integer, desc: "HTTP status code"
+end
+
+# Common response objects
+ApiRegulator.register_shared_schema :pagination_meta, "Pagination metadata" do
+  param :current_page, :integer, desc: "Current page number"
+  param :per_page, :integer, desc: "Items per page"
+  param :total_pages, :integer, desc: "Total number of pages"
+  param :total_count, :integer, desc: "Total number of items"
 end
 ```
 
-Reference the shared schema in your responses:
+Use shared schemas in your API definitions:
+
 ```ruby
-  response 422, ref: :validation_errors
+api self, :index do
+  param :page, :integer, location: :query, desc: "Page number"
+  param :per_page, :integer, location: :query, desc: "Items per page"
+
+  response 200, "List of customers" do
+    param :customers, :array do
+      ref :customer_summary  # Reference another shared schema
+    end
+    ref :pagination_meta
+  end
 end
 ```
 
-## Generating OpenAPI Documentation
+### Webhook Documentation
 
-Generate OpenAPI documentation using the provided Rake tasks:
+Define webhook payloads using the same DSL:
+
+```ruby
+class WebhookDefinitions < Api::ApplicationController
+  webhook :customer_created, 
+    desc: "Fired when a new customer is created",
+    title: "Customer Created",
+    tags: ["customers", "webhooks"] do
+    
+    param :event, :string, desc: "Event name"
+    param :timestamp, :string, desc: "ISO 8601 timestamp"
+    param :data do
+      param :customer do
+        param :id, :string, desc: "Customer UUID"
+        param :email, :string, desc: "Customer email"
+        param :created_at, :string, desc: "ISO 8601 timestamp"
+      end
+    end
+
+    example :basic_example, {
+      event: "customer.created",
+      timestamp: "2024-01-15T10:30:00Z",
+      data: {
+        customer: {
+          id: "cust_abc123",
+          email: "john@example.com",
+          created_at: "2024-01-15T10:30:00Z"
+        }
+      }
+    }, default: true
+  end
+end
+```
 
+### API Examples
 
-1. **Generate the Schema:**
-   ```bash
-   rake api_docs:generate # uses default (or no) version
-   VERSION=v1.0-internal rake api_docs:generate # specifies the to generate
-   ```
+Add examples to your API definitions:
 
-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.
+```ruby
+api self, :create do
+  param :customer do
+    param :name, :string, presence: true
+    param :email, :string, presence: true
+  end
+
+  example :successful_creation, {
+    customer: {
+      name: "John Doe",
+      email: "john@example.com"
+    }
+  }, default: true
+
+  example :with_optional_fields, {
+    customer: {
+      name: "Jane Smith",
+      email: "jane@example.com",
+      phone: "+1-555-0123"
+    }
+  }
+end
+```
+
+## Validation and Error Handling
+
+### Automatic Parameter Validation
+
+```ruby
+def create
+  validate_params! # Raises ApiRegulator::InvalidParams or ApiRegulator::UnexpectedParams
+  
+  # Access validated and type-converted parameters
+  customer_data = api_params[:customer]
+  # Process with confidence that data is valid
+end
+```
+
+### Custom Error Handling
+
+```ruby
+class Api::ApplicationController < ActionController::API
+  include ApiRegulator::DSL
+  include ApiRegulator::ControllerMixin
+
+  rescue_from ApiRegulator::InvalidParams do |exception|
+    render json: { 
+      errors: exception.errors.messages,
+      message: "Validation failed" 
+    }, status: :unprocessable_entity
+  end
+
+  rescue_from ApiRegulator::UnexpectedParams do |exception|
+    render json: { 
+      errors: exception.details,
+      message: "Unexpected parameters provided" 
+    }, status: :bad_request
+  end
+end
+```
 
-3. **Publish Both**:
-   ```bash
-   rake api_docs:publish
-   ```
+## OpenAPI Documentation Generation
 
-## 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.
+### Generate Documentation
 
-## Releasing a new version
-`api-regulator` is published to [rubygems](https://rubygems.org/gems/api-regulator). To release a new version,
-1. In your PR, bump the version in `lib/api_regulator/version.rb`
-2. Run `bundle install` (this should update your `Gemfile.lock`)
-3. Go through code review and merge your PR
-4. Trigger the [`Release Gem`](https://github.com/Stellarcred/api-regulator/actions/workflows/release.yml) workflow from the main branch.
-5. Verify your new version is available in [rubygems](https://rubygems.org/gems/api-regulator).
+```bash
+# Generate for default version
+rake api_docs:generate
+
+# Generate for specific version
+VERSION=v1.0 rake api_docs:generate
+
+# Generate for all configured versions
+rake api_docs:generate_all
+```
+
+### Upload to ReadMe
+
+Set up your ReadMe credentials:
+
+```bash
+export RDME_API_KEY="your_readme_api_key"
+```
+
+```bash
+# Upload API specification
+rake api_docs:upload
+
+# Upload custom documentation pages (with YAML frontmatter)
+rake api_docs:upload_pages
+
+# Generate and upload everything
+rake api_docs:publish
+```
+
+### Custom Documentation Pages
+
+Create markdown files in your `docs_path` with YAML frontmatter:
+
+```markdown
+---
+title: "Getting Started"
+slug: "getting-started"
+category: "documentation"
+hidden: false
+---
+
+# Getting Started
+
+Your API documentation content here...
+```
+
+### ReadMe Integration Features
+
+```bash
+# Fetch available categories
+rake api_docs:fetch_categories
+
+# Upload with specific version
+VERSION=v2.0 rake api_docs:upload
+```
+
+## Built-in Format Validators
+
+ApiRegulator includes common format validators:
+
+```ruby
+ApiRegulator::Formats::DATE          # ISO 8601 date format
+ApiRegulator::Formats::DATETIME      # ISO 8601 datetime format  
+ApiRegulator::Formats::EMAIL         # Email address validation
+ApiRegulator::Formats::ZIP_CODE      # US ZIP code (12345 or 12345-6789)
+ApiRegulator::Formats::URI           # URI format validation
+```
+
+Usage example:
+
+```ruby
+param :email, :string, format: { with: ApiRegulator::Formats::EMAIL }
+param :website, :string, format: { with: ApiRegulator::Formats::URI }
+param :birth_date, :string, format: { with: ApiRegulator::Formats::DATE }
+```
+
+## Testing Your APIs
+
+ApiRegulator integrates seamlessly with RSpec:
+
+```ruby
+RSpec.describe Api::V1::CustomersController do
+  describe "POST /api/v1/customers" do
+    it "validates required parameters" do
+      post "/api/v1/customers", params: {}
+      expect(response).to have_http_status(:unprocessable_entity)
+    end
+
+    it "creates customer with valid parameters" do
+      params = {
+        customer: {
+          first_name: "John",
+          last_name: "Doe", 
+          email: "john@example.com"
+        }
+      }
+      
+      post "/api/v1/customers", params: params
+      expect(response).to have_http_status(:created)
+    end
+  end
+end
+```
+
+## Configuration Reference
+
+```ruby
+ApiRegulator.configure do |config|
+  # Base URL for all API endpoints (default: "api/v1")
+  config.api_base_url = "/api/v1"
+  
+  # Application name shown in documentation (default: "API Documentation")
+  config.app_name = "My API"
+  
+  # Directory for documentation files (default: "doc")
+  config.docs_path = Rails.root.join("doc").to_s
+  
+  # Version mapping for ReadMe (optional)
+  config.versions = {
+    "v1.0" => "readme_spec_id_1",
+    "v2.0" => "readme_spec_id_2"
+  }
+  
+  # Default version when none specified (optional)
+  config.default_version = "v1.0"
+  
+  # Server definitions for OpenAPI spec (optional)
+  config.servers = [
+    { url: "https://api.example.com", description: "Production" },
+    { url: "https://staging-api.example.com", description: "Staging" }
+  ]
+end
+```
+
+## Advanced Usage
+
+### Multiple API Versions
+
+```ruby
+# Define version-specific endpoints
+api self, :create, versions: [:v1, :v2] do
+  param :name, :string, presence: true
+  param :email, :string, presence: true, versions: [:v1, :v2] 
+  param :phone, :string, versions: [:v2]  # Only in v2
+end
+```
+
+### Security Requirements
+
+```ruby
+api self, :create do
+  # This endpoint requires authentication
+  security [{ bearer_auth: [] }]
+  
+  param :customer do
+    param :name, :string, presence: true
+  end
+end
+```
+
+### Custom Validation Context
+
+```ruby
+def update
+  # Validate with specific context
+  validate_params!
+  
+  # The validation context is automatically set to the action name (:update)
+  # This allows conditional validations based on the action
+end
+```
+
+## Error Reference
+
+- `ApiRegulator::InvalidParams`: Raised when request parameters fail validation
+- `ApiRegulator::UnexpectedParams`: Raised when unexpected parameters are provided
+- `ApiRegulator::ValidationError`: Base class for validation errors
+
+## Development and Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/new-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass (`bundle exec rspec`)
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin feature/new-feature`)
+7. Open a pull request
+
+### Running Tests
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Releasing New Versions
+
+ApiRegulator is published to [RubyGems](https://rubygems.org/gems/api-regulator). To release:
+
+1. Update version in `lib/api_regulator/version.rb`
+2. Run `bundle install` to update `Gemfile.lock`
+3. Create PR and merge after review
+4. Trigger the [Release Gem workflow](https://github.com/Stellarcred/api-regulator/actions/workflows/release.yml)
+5. Verify publication on [RubyGems](https://rubygems.org/gems/api-regulator)
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 8.0 (ActiveSupport and ActiveModel)
 
 ## License
+
 This gem is available as open-source software under the [MIT License](https://mit-license.org/).

data/lib/api_regulator/api.rb

@@ -1,15 +1,16 @@
 module ApiRegulator
   class Api
     attr_reader :controller_class, :controller_path, :controller_name, :action_name, :description,
-      :title, :params, :responses, :versions, :examples
+      :title, :params, :responses, :versions, :examples, :tags
 
-    def initialize(controller_class, action_name, desc: nil, title: nil, versions: [], &block)
+    def initialize(controller_class, action_name, desc: nil, title: nil, versions: [], tags: [], &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
+      @tags = tags.presence || default_tags
       @versions = Array(versions).map(&:to_sym)
 
       @params = []
@@ -88,7 +89,7 @@ module ApiRegulator
       "#{controller_path.gsub("/", "-")}-#{action_name}"
     end
 
-    def tags
+    def default_tags
       [
         controller_name
           .demodulize

data/lib/api_regulator/dsl.rb

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

data/lib/api_regulator/version.rb

@@ -1,3 +1,3 @@
 module ApiRegulator
-  VERSION = "0.1.27"
+  VERSION = "0.1.28"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api-regulator
 version: !ruby/object:Gem::Version
-  version: 0.1.27
+  version: 0.1.28
 platform: ruby
 authors:
 - Geoff Massanek
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-17 00:00:00.000000000 Z
+date: 2025-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport