# 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.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
     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.register_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/).