api-regulator 0.1.27 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1930002f6e2b1b916f44c2aaf447b624c373f5393297d7aa12b665063ec75a56
-  data.tar.gz: f98dc9238b359bf019eeffe6f0f5a3a0dc001f8f8af91d80ba042828621cd699
+  metadata.gz: 8bcf52fc47c491d424f53b82688cfa8a3f0b78b62460267f1ad81abcf695827d
+  data.tar.gz: 1bb55ea5e11bff7fce98874adf0ca5d79db2431eabf4cafdaaf2dec7b4bb6fa4
 SHA512:
-  metadata.gz: effb1e8e1cac07f20aa41dd4398b146afa13a59769c687bfc740730ae3a9bf7a84d81805dc11e0a0073c97c3375689d6d78647bef7cc1543ede8c065c1956474
-  data.tar.gz: a951dc617505560736c62a34aa4eae3d2c99364a39953ee64d337c232b516f9949d1cf90de9859d9d9b33c2036f42fc9421ea7ceabdf5ae81099b4f4bc9b8675
+  metadata.gz: c872be90e74a524e316958afc1486464612854794ca86f0fe78aef6ea9a67bc1779870eecd7fc8750987e0a5f3b2ca5a99c7af6047add3f3fb83d0e86c326d8b
+  data.tar.gz: e55567f1b2c788bae49bb536aee0aa10e9f6fa6c490ec04632c42a0b6acb0fb2758c54ef6c7944806aeb3453c197cf2bce749977c324d523dbca1c88eb19bf44

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    api-regulator (0.1.27)
+    api-regulator (1.0.0)
       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 generating OpenAPI specs and seamless integration with rdme CLI for uploading 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,705 @@ gem 'api_regulator'
 
 Run `bundle install` to install the gem.
 
+### Optional: Install rdme CLI for ReadMe Integration
 
-## Setup
+For uploading documentation to ReadMe, install the rdme CLI:
 
-1. **Create an Initializer**:
+```bash
+npm install -g rdme
+```
 
-   Add the following to `config/initializers/api_regulator.rb`:
+Or as a project dependency:
 
-   ```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
+```bash
+npm install rdme --save-dev
+```
 
-     # Optional: ReadMe versions and API ID for schema uploads
-     config.versions = {
-       "v1.0" => "abc123",
-       "v1.0-internal" => "abc345"
-     }
-     config.default_version = "v1.0-internal"
+## Setup
 
-     config.servers = [
-       { url: "https://stg.example.com", description: "Staging", "x-default": true },
-       { url: "https://example.com", description: "Production" }
-     ]
-   end
-   ```
+### 1. Create an Initializer
 
-2. **Include the DSL in Your Base Controller**:
+Add the following to `config/initializers/api_regulator.rb`:
 
-   Include the DSL and validation methods in your base API controller:
+```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
+```
 
-   ```ruby
-   class Api::ApplicationController < ActionController::API
-     include ApiRegulator::DSL
-     include ApiRegulator::ControllerMixin
-   end
-   ```
+### 2. Include the DSL in Your Base Controller
 
-## Usage
+```ruby
+class Api::ApplicationController < ActionController::API
+  include ApiRegulator::DSL
+  include ApiRegulator::ControllerMixin
+end
+```
 
-**Defining Endpoints**
+### 3. Define Security Schemes (Optional)
 
-Use the DSL in your controllers to define API endpoints, request parameters, and response schemas.
+```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
+
+### 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
+    validate_params! # Validates against DSL definition
 
-    customer = Customer.create!(api_params[:customer]) # Use dynamically generated params
-    render json: customer, status: :ok
+    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
+```
+
+Use shared schemas in your API definitions:
+
+```ruby
+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
+```
+
+### Webhook Documentation
+
+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
+
+Add examples to your API definitions:
+
+```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
+```
+
+## OpenAPI Documentation Generation
+
+### Validate OpenAPI Specification
+
+Before uploading, validate your OpenAPI specification using rdme:
+
+```bash
+# Validate the generated OpenAPI spec
+rdme openapi validate doc/openapi.yaml
+
+# Validate with specific version
+rdme openapi validate doc/openapi.yaml --version=v1.0
+```
+
+### Generate Documentation
+
+```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
+
+ApiRegulator integrates with [rdme](https://github.com/readmeio/rdme), ReadMe's official CLI tool, for modern, secure, and reliable documentation management.
+
+#### Installation
+
+Install the rdme CLI globally:
+
+```bash
+npm install -g rdme
+```
+
+Or install it as a project dependency:
+
+```bash
+npm install rdme --save-dev
+```
+
+#### Authentication
+
+Authenticate with ReadMe using the CLI:
+
+```bash
+rdme login
+```
+
+Alternatively, set your API key as an environment variable:
+
+```bash
+export RDME_API_KEY="your_readme_api_key"
+```
+
+#### Upload Commands
+
+**Recommended approach using rdme CLI:**
+
+```bash
+# Generate and upload everything using rdme (RECOMMENDED)
+rake api_docs:publish_rdme
+
+# Or step by step:
+rake api_docs:generate
+rake api_docs:upload_rdme
+rdme docs upload doc/
+```
+
+**Legacy approach (may not work with ReadMe API v2):**
+
+```bash
+# Generate OpenAPI specification
+rake api_docs:generate
+
+# Upload using legacy rake tasks (deprecated)
+rake api_docs:upload
+rake api_docs:upload_pages
+```
+
+#### Migration from Legacy Tasks
+
+If you're experiencing 404 errors with the legacy upload tasks, migrate to rdme CLI:
+
+```bash
+# Run the migration script
+./scripts/migrate_to_rdme.sh
+
+# Or manually:
+npm install -g rdme
+rdme login
+rake api_docs:publish_rdme
+```
+
+**rdme CLI Features:**
+
+- Modern ReadMe API v2 integration
+- Bearer token authentication (more secure)
+- Better performance and reliability
+- Support for ReadMe Refactored features
+- Branch-based versioning
+- Built-in validation and error handling
+
+### 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...
+```
+
+### GitHub Actions Integration
+
+Use rdme in your GitHub Actions workflow for automated documentation updates:
+
+```yaml
+name: Update API Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  update-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0
+
+      - name: Install dependencies
+        run: |
+          gem install bundler
+          bundle install
+
+      - name: Generate and upload API documentation
+        run: rake api_docs:publish_rdme
+        env:
+          RDME_API_KEY: ${{ secrets.RDME_API_KEY }}
+```
+
+### ReadMe Integration Features
+
+```bash
+# Validate OpenAPI specification
+rdme openapi validate doc/openapi.yaml
+
+# Upload OpenAPI spec using rake task (recommended)
+rake api_docs:upload_rdme
+
+# Upload with specific version
+VERSION=v2.0 rake api_docs:upload_rdme
+
+# Upload directly with rdme CLI
+rdme openapi upload doc/openapi.yaml --version=v2.0
+
+# Fetch available categories
+rdme categories list
+```
+
+## 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
 ```
 
-Reference the shared schema in your responses:
+### Custom Validation Context
+
 ```ruby
-  response 422, ref: :validation_errors
+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
 ```
 
-## Generating OpenAPI Documentation
+## Troubleshooting
+
+### Common Issues
+
+#### 404 Error When Uploading Pages
+
+If you get a 404 error when uploading documentation pages:
+
+```
+Failed to upload page 'Webhooks'!
+Response Code: 404
+```
+
+**Solution:** The legacy rake tasks may not work with ReadMe API v2. Use rdme CLI instead:
+
+```bash
+# Install and authenticate with rdme
+npm install -g rdme
+rdme login
+
+# Use the recommended approach
+rake api_docs:publish_rdme
+```
+
+#### Authentication Issues
+
+If you get authentication errors:
+
+```bash
+# Check your authentication status
+rdme whoami
+
+# Re-authenticate if needed
+rdme logout
+rdme login
+```
+
+#### OpenAPI Validation Errors
+
+Validate your OpenAPI spec before uploading:
+
+```bash
+# Validate the generated spec
+rdme openapi validate doc/openapi.yaml
+
+# Check for common issues
+rdme openapi validate doc/openapi.yaml --verbose
+```
+
+## Error Reference
 
-Generate OpenAPI documentation using the provided Rake tasks:
+- `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. **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
-   ```
+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
 
-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.
+### Running Tests
+
+```bash
+bundle install
+bundle exec rspec
+```
 
-3. **Publish Both**:
-   ```bash
-   rake api_docs:publish
-   ```
+## Releasing New Versions
 
-## 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.
+ApiRegulator is published to [RubyGems](https://rubygems.org/gems/api-regulator). To release:
 
-## 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).
+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/configuration.rb

@@ -4,7 +4,7 @@ module ApiRegulator
 
     def initialize
       # Set default values
-      @api_base_url = "api/v1"
+      @api_base_url = "api/v2"
       @app_name = "API Documentation"
       @docs_path = "doc"
       @servers = []

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/open_api_generator.rb

@@ -30,12 +30,12 @@ module ApiRegulator
         openapi: '3.1.0', # Explicitly target OpenAPI 3.1.0
         info: {
           title: ApiRegulator.configuration.app_name,
-          description: 'Generated by ApiRegulator'
+          description: 'Generated by ApiRegulator',
+          version: version.presence || '1.0.0'
         },
         servers: ApiRegulator.configuration.servers,
         paths: {}
       }
-      final_schema[:info][:version] = version if version.present?
 
       add_components
       add_security

data/lib/api_regulator/version.rb

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

data/lib/tasks/api_regulator_tasks.rake

@@ -23,128 +23,116 @@ namespace :api_docs do
     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"
+  desc "Upload OpenAPI schema to ReadMe using rdme CLI (RECOMMENDED)"
+  task upload_rdme: :environment do
+    # Check if rdme is available
+    unless system("which rdme > /dev/null 2>&1")
+      puts "❌ rdme CLI not found. Please install it first:"
+      puts "   npm install -g rdme"
+      puts "   rdme login"
+      exit 1
+    end
 
-    # Read the OpenAPI schema file
-    schema_path =  ApiRegulator::OpenApiGenerator.schema_file_path(version: version)
+    version = ENV['VERSION'] || ApiRegulator.configuration.default_version
+    schema_path = ApiRegulator::OpenApiGenerator.schema_file_path(version: version)
+    
     unless File.exist?(schema_path)
-      raise "OpenAPI schema file not found at #{schema_path}"
+      raise "OpenAPI schema file not found at #{schema_path}. Run 'rake api_docs:generate' first."
     end
-    openapi_content = File.read(schema_path)
 
-    # Upload to ReadMe
-    require 'net/http'
-    require 'uri'
-    require 'json'
+    puts "📄 Uploading OpenAPI specification with rdme CLI..."
+    puts "   Schema: #{schema_path}"
+    puts "   Version: #{version || 'default'}"
+    puts ""
 
-    if version.present?
-      uri = URI.parse("#{readme_api_endpoint}/#{ApiRegulator.configuration.versions[version]}")
-      request = Net::HTTP::Put.new(uri)
+    # Use rdme CLI to upload
+    if system("rdme openapi upload #{schema_path}")
+      puts "✅ OpenAPI schema successfully uploaded!"
     else
-      uri = URI.parse(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["x-readme-version"] = version if version.present?
-    request.body = {
-      spec: JSON.parse(openapi_content)
-    }.to_json
-
-    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
-      http.request(request)
+      puts "❌ Failed to upload OpenAPI schema"
+      exit 1
     end
+  end
 
-    if response.code.to_i == 200
-      puts "OpenAPI schema successfully updated!"
-    elsif response.code.to_i == 201
-      puts "OpenAPI schema successfully created!"
-      puts "To use this for future publishing, add this to your ApiRegulator configs:"
-      puts ""
-      puts "  config.versions = {"
-      puts "    \"<versionNumber>\": \"#{JSON.parse(response.body)["_id"]}\""
-      puts "  }"
-      puts ""
+  desc "Upload OpenAPI schema to ReadMe (LEGACY - may not work with ReadMe API v2)"
+  task :upload => :environment do
+    puts "⚠️  WARNING: This rake task is deprecated and may not work with ReadMe API v2."
+    puts "   Please use the rdme CLI instead:"
+    puts "   "
+    puts "   # Install rdme CLI"
+    puts "   npm install -g rdme"
+    puts "   "
+    puts "   # Authenticate with ReadMe"
+    puts "   rdme login"
+    puts "   "
+    puts "   # Upload using rdme CLI"
+    puts "   rake api_docs:upload_rdme"
+    puts "   "
+    puts "   For more information, see: https://github.com/readmeio/rdme"
+    puts "   "
+    
+    # Check if rdme is available
+    if system("which rdme > /dev/null 2>&1")
+      puts "✅ rdme CLI is installed. Running: rake api_docs:upload_rdme"
+      Rake::Task["api_docs:upload_rdme"].invoke
     else
-      puts "Failed to upload OpenAPI schema to ReadMe!"
-      puts "Response Code: #{response.code}"
-      puts "Response Body:"
-      pp JSON.parse(response.body)
+      puts "❌ rdme CLI not found. Please install it first:"
+      puts "   npm install -g rdme"
+      exit 1
     end
   end
 
-  desc 'Generate and upload OpenAPI schema'
+  desc 'Generate and upload OpenAPI schema using rdme CLI (RECOMMENDED)'
+  task publish_rdme: :environment do
+    Rake::Task["api_docs:generate"].invoke
+    Rake::Task["api_docs:upload_rdme"].invoke
+    
+    puts "📄 Uploading documentation pages with rdme CLI..."
+    system("rdme docs upload #{ApiRegulator.configuration.docs_path}/")
+  end
+
+  desc 'Generate and upload OpenAPI schema (LEGACY - may not work with ReadMe API v2)'
   task publish: :environment do
     Rake::Task["api_docs:generate"].invoke
     Rake::Task["api_docs:upload"].invoke
-    Rake::Task["api_docs:upload_pages"].invoke
+    
+    # Check if rdme is available for uploading pages
+    if system("which rdme > /dev/null 2>&1")
+      puts "📄 Uploading documentation pages with rdme CLI..."
+      system("rdme docs upload #{ApiRegulator.configuration.docs_path}/")
+    else
+      puts "⚠️  rdme CLI not found. Skipping documentation pages upload."
+      puts "   Install rdme CLI to upload documentation pages:"
+      puts "   npm install -g rdme"
+      puts "   rdme docs upload #{ApiRegulator.configuration.docs_path}/"
+    end
   end
 
-  desc "Upload custom pages to ReadMe"
+  desc "Upload custom pages to ReadMe (DEPRECATED - Use rdme CLI instead)"
   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
-    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("_", "-")
-      request_body = {
-        type: "basic",
-        categorySlug: "documentation",
-        hidden: false,
-        body: body
-      }.merge(metadata)
-      request_body["slug"] ||= slug
-
-      raise("Title missing in #{file_path}") unless request_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["x-readme-version"] = version if version.present?
-      request.body = request_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 '#{request_body["title"]}' successfully updated!"
-      when 201
-        puts "Page '#{request_body["title"]}' successfully created!"
-      else
-        puts "Failed to upload page '#{request_body["title"]}'!"
-        puts "Response Code: #{response.code}"
-        puts "Response Body: #{response.body}"
-      end
+    puts "⚠️  WARNING: This rake task is deprecated and may not work with ReadMe API v2."
+    puts "   Please use the rdme CLI instead:"
+    puts "   "
+    puts "   # Install rdme CLI"
+    puts "   npm install -g rdme"
+    puts "   "
+    puts "   # Authenticate with ReadMe"
+    puts "   rdme login"
+    puts "   "
+    puts "   # Upload documentation pages"
+    puts "   rdme docs upload #{ApiRegulator.configuration.docs_path}/"
+    puts "   "
+    puts "   For more information, see: https://github.com/readmeio/rdme"
+    puts "   "
+    
+    # Check if rdme is available
+    if system("which rdme > /dev/null 2>&1")
+      puts "✅ rdme CLI is installed. Running: rdme docs upload #{ApiRegulator.configuration.docs_path}/"
+      system("rdme docs upload #{ApiRegulator.configuration.docs_path}/")
+    else
+      puts "❌ rdme CLI not found. Please install it first:"
+      puts "   npm install -g rdme"
+      exit 1
     end
   end
 
@@ -152,15 +140,13 @@ 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"
+    readme_categories_api_endpoint = "https://api.readme.com/v2/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["Authorization"] = "Bearer #{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|
@@ -171,7 +157,10 @@ namespace :api_docs do
     case response.code.to_i
     when 200
       puts "Categories"
-      pp JSON.parse(response.body)
+      response_data = JSON.parse(response.body)
+      # API v2 response format - returns data in a 'data' wrapper
+      categories = response_data.dig("data") || response_data
+      pp categories
     else
       puts "Failed to fetch categories"
       puts "Response Code: #{response.code}"
@@ -195,14 +184,13 @@ namespace :api_docs do
     [metadata, body]
   end
 
-  def check_if_page_exists(slug)
+  def check_if_page_exists(slug, branch = "stable")
     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}")
+    
+    uri = URI.parse("https://api.readme.com/v2/custom_pages/#{slug}")
     request = Net::HTTP::Get.new(uri)
-    request["Authorization"] = "Basic #{Base64.strict_encode64(readme_api_key)}"
+    request["Authorization"] = "Bearer #{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.27
+  version: 1.0.0
 platform: ruby
 authors:
 - Geoff Massanek
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-17 00:00:00.000000000 Z
+date: 2025-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport