README.md

OpenapiRailsTypedParameters

openapi_rails_typed_parameters is a library for performing parameter validation and coercion in Rails using OpenAPI definition files. It also supports providing static types through RBS generation.

This gem internally uses the openapi_first gem.

Main Objectives

• Eliminate the code for params validation and type conversion (which is always a boring and routine task)
• Provide an RBS generator (so you don't have to memorize parameters)

Differences from the openapi_first gem

• Offers more tightly coupled features to Rails
• Assists in statically typed programming by providing an RBS generator

⚠️ This gem is under development.

This gem is currently under development. It is not recommended for use in production applications. Backward compatibility is not guaranteed until version 1.0.0 is released.

Once all of the following TODOs are completed, we will release version 1.0.0.

TODO

• Coercion to more Rails application appropriate types, such as ActiveSupport::TimeWithZone
• Provide more opinionated options for type conversions, such as coercion to Symbol for Enum value
• Include a RBS generation generator for statically typed programming
• Include RBS in the gem itself

Installation

Add openapi_rails_typed_parameters to your Gemfile.

gem 'openapi_rails_typed_parameters'

Usage

Please add an initializer to your Rails application and specify the path to the OpenAPI schema file.

e.g.) config/initializers/openapi.rb

require 'openapi_rails_typed_parameters'

OpenapiRailsTypedParameters.configure do |config|
  config.schema_path = Rails.root.join('schema.yml')
end

Then, add using OpenapiRailsTypedParameters to your controller class. You can access statically typed parameters via typed_parameters method.

Example

openapi: 3.0.3
info:
  version: 1.0.0
  title: Sample App
servers:
  - url: https://example.com/
paths:
  /users:
    get:
      parameters:
        - name: role
          in: query
          required: true
          schema:
            type: string
            enum: [ admin, maintainer ]
        - name: minimum
          in: query
          required: false
          schema:
            type: integer
        - name: maximum
          in: query
          required: false
          schema:
            type: integer

class UsersController < ApplicationController
  using OpenapiRailsTypedParameters

  def index
    typed_params.validate!
    res = {
      role: typed_params.query_params.role # 'admin' or 'maintainer',
      minimum: typed_params.query_params.minimum # Integer value
      maximum: typed_params.query_params.maximum # Integer value
    }
    render json: res
  rescue OpenapiFirst::RequestInvalidError => e
    res = {
      # e.g.)
      # Query parameter is invalid: value at `/role` is not one of: ["admin", "maintainer"]
      message: e.message
    }
    render json: res, status: :bad_request
  end
end

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the OpenapiRailsTypedParameters project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.