json_schemer-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89d0c994e82f4c3cf3aa35d35f2d0628f1316e72628bb8df14b8233047dd3d8f
+  data.tar.gz: 9e652b939fa51ff62be60cafc8f537636248c403309bb9b1ea2f81cc573e8c73
+SHA512:
+  metadata.gz: 13e88600a91331896d6d469ffb8dff696d8ad5a669a196c7faadbcc416ff86a3f1000d5e00903cd50647a0b05a916674d267ff10e31ad4ec2e542179abb1f1f1
+  data.tar.gz: d1a8fe5daa2463e88050d6d1248f3f6e603dde344909a1d8540bcc960bfa03e5349e1d1e29d89378575131f987f9d19368014422ae7a6ef5e996847d67249e33

data/README.md

@@ -0,0 +1,330 @@
+# JsonSchemer::Rails
+
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.4.0-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%208.0-red.svg)](https://rubyonrails.org/)
+
+A Rails integration for [json_schemer](https://github.com/davishmcclurg/json_schemer) that provides OpenAPI 3.0 request validation and parameter type casting for your Rails controllers.
+
+## Features
+
+- ✅ Validates request bodies against OpenAPI 3.0 schemas
+- ✅ Validates path and query parameters
+- ✅ Automatic type casting for query parameters (strings to booleans, integers, etc.)
+- ✅ Schema references (`$ref`) support
+- ✅ Content-Type validation
+- ✅ Comprehensive error messages
+- ✅ Easy integration with Rails controllers
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'json_schemer-rails'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### 1. Create an OpenAPI Specification
+
+Create an `openapi.yml` file in your Rails root directory:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+paths:
+  /users:
+    post:
+      summary: Create a user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                email:
+                  type: string
+                  format: email
+                age:
+                  type: integer
+              required:
+                - name
+                - email
+      parameters:
+        - name: notify
+          in: query
+          schema:
+            type: boolean
+      responses:
+        '201':
+          description: User created
+  /users/{id}:
+    get:
+      summary: Get a user
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: '^[0-9]+$'
+      responses:
+        '200':
+          description: User details
+```
+
+### 2. Include in Your Controller
+
+#### Option A: Use the Controller Mixin (Recommended)
+
+```ruby
+class UsersController < ApplicationController
+  include JsonSchemer::Rails::Controller
+  
+  before_action :validate_from_openapi, only: [:create, :update]
+
+  def create
+    # At this point:
+    # - Request body has been validated against the schema
+    # - Query parameters have been type-cast (e.g., "true" → true)
+    # - Path parameters have been validated
+    
+    user = User.create!(params.permit(:name, :email, :age))
+    render json: user, status: :created
+  end
+end
+```
+
+#### Option B: Manual Validation
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    validator = JsonSchemer::Rails::OpenApiValidator.new(request)
+    
+    # Validate and cast parameters
+    validator.validated_params
+    
+    # Validate request body
+    errors = validator.validate_body.to_a
+    if errors.any?
+      render json: { errors: errors }, status: :unprocessable_entity
+      return
+    end
+    
+    user = User.create!(params.permit(:name, :email, :age))
+    render json: user, status: :created
+  end
+end
+```
+
+### 3. Custom OpenAPI File Location
+
+By default, the validator looks for `openapi.yml` in your Rails root. You can specify a different location:
+
+```ruby
+validator = JsonSchemer::Rails::OpenApiValidator.new(
+  request,
+  open_api_filename: Rails.root.join('config', 'api_schema.yml')
+)
+```
+
+## How It Works
+
+### Request Body Validation
+
+The validator automatically:
+- Checks that the `Content-Type` header is set to `application/json` for POST/PUT/PATCH requests
+- Parses the request body as JSON
+- Validates the JSON against the schema defined in your OpenAPI spec
+- Returns detailed validation errors if the body doesn't match the schema
+
+### Parameter Validation and Type Casting
+
+The validator processes both query and path parameters:
+
+#### Query Parameters
+- **Type Casting**: Converts string values to their specified types
+  - `"true"`, `"1"` → `true`
+  - `"false"`, `"0"` → `false`
+  - Numbers are cast to integers/floats as specified
+- **Validation**: Ensures parameters match their schema definitions
+- **Unknown Parameters**: Ignores parameters not defined in the OpenAPI spec
+
+#### Path Parameters
+- Validates against schema patterns (e.g., regex patterns)
+- Validates against referenced schemas (`$ref`)
+- Raises `RequestValidationError` if validation fails
+
+### Example: Type Casting in Action
+
+Given this OpenAPI parameter definition:
+
+```yaml
+parameters:
+  - name: notify
+    in: query
+    schema:
+      type: boolean
+  - name: limit
+    in: query
+    schema:
+      type: integer
+```
+
+Query string: `?notify=true&limit=10`
+
+Before validation:
+```ruby
+params[:notify] # => "true" (String)
+params[:limit]  # => "10" (String)
+```
+
+After `validated_params`:
+```ruby
+params[:notify] # => true (Boolean)
+params[:limit]  # => "10" (String, not cast because OpenAPI handles this differently)
+```
+
+## Error Handling
+
+When validation fails, a `JsonSchemer::Rails::RequestValidationError` is raised:
+
+```ruby
+class ApplicationController < ActionController::API
+  rescue_from JsonSchemer::Rails::RequestValidationError do |exception|
+    render json: { error: exception.message }, status: :unprocessable_entity
+  end
+end
+```
+
+## Testing
+
+The gem includes comprehensive RSpec tests. To run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+### Writing Tests for Your Controllers
+
+Use `ActionDispatch::TestRequest` to test your validated endpoints:
+
+```ruby
+require 'rails_helper'
+
+RSpec.describe UsersController, type: :controller do
+  describe 'POST #create' do
+    it 'validates the request body' do
+      request.headers['Content-Type'] = 'application/json'
+      post :create, body: { name: 'John', email: 'john@example.com' }.to_json
+      
+      expect(response).to have_http_status(:created)
+    end
+    
+    it 'rejects invalid requests' do
+      request.headers['Content-Type'] = 'application/json'
+      post :create, body: { name: 'John' }.to_json # missing email
+      
+      expect(response).to have_http_status(:unprocessable_entity)
+    end
+  end
+end
+```
+
+## Advanced Usage
+
+### Skipping Validation for Specific Actions
+
+```ruby
+class UsersController < ApplicationController
+  include JsonSchemer::Rails::Controller
+  
+  before_action :validate_from_openapi, except: [:index]
+  
+  def index
+    # No validation needed for GET requests without body
+  end
+  
+  def create
+    # Validated automatically
+  end
+end
+```
+
+### Custom Validation Logic
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    validator = JsonSchemer::Rails::OpenApiValidator.new(request)
+    
+    # Validate parameters first
+    validator.validated_params
+    
+    # Then validate body
+    body_errors = validator.validate_body.to_a
+    
+    # Add custom validation
+    custom_errors = custom_business_logic_validation
+    
+    all_errors = body_errors + custom_errors
+    if all_errors.any?
+      render json: { errors: all_errors }, status: :unprocessable_entity
+      return
+    end
+    
+    # Proceed with valid data
+  end
+  
+  private
+  
+  def custom_business_logic_validation
+    # Your custom validation logic
+    []
+  end
+end
+```
+
+## Requirements
+
+- Ruby >= 3.4.0
+- Rails >= 8.0
+- json_schemer >= 2.5
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sul-dlss/json_schemer-rails.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Built with [json_schemer](https://github.com/davishmcclurg/json_schemer) by Davis W. McGuire.
+
+Developed by [Stanford Digital Library](https://library.stanford.edu/).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/json_schemer/rails/controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module JsonSchemer
+  module Rails
+    # Mixin for controllers.
+    # usage:
+    #   include JsonSchemer::Rails::Controller
+    #   before_actoin :validate_from_openapi
+    module Controller
+      def validate_from_openapi
+        # This is going to cast any parameters to their specified types
+        openapi_validator.validated_params
+
+        errors = openapi_validator.validate_body.to_a
+        raise(RequestValidationError, errors.pluck("error").join("; ")) if errors.any?
+      end
+
+      private
+
+      def openapi_validator
+        @openapi_validator ||= OpenApiValidator.new(request)
+      end
+    end
+  end
+end

data/lib/json_schemer/rails/open_api_validator.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "yaml"
+require "json_schemer"
+
+module JsonSchemer
+  module Rails
+    # This validates a request against the OpenAPI specification
+    class OpenApiValidator
+      def initialize(request, open_api_filename: "openapi.yml")
+        @request = request
+        @open_api_filename = open_api_filename
+      end
+
+      attr_reader :request
+
+      def validate_body
+        return unless should_validate_body?
+
+        unless request.content_type == "application/json"
+          raise RequestValidationError,
+                '"Content-Type" request header must be set to "application/json".'
+        end
+
+        document.ref("#{request_openapi_path}/requestBody/content/application~1json/schema")
+                .validate(JSON.parse(request.body.read))
+      end
+
+      # cast any parameters that are not part of the OpenAPI specification
+      def validated_params
+        param_specs = document.ref(request_openapi_path).value["parameters"] || []
+
+        param_specs.each do |spec|
+          case spec["in"]
+          when "query"
+            validate_query_param(spec)
+          when "path"
+            validate_path_param(spec)
+          end
+        end
+      end
+
+      private
+
+      def should_validate_body?
+        return false if %w[delete get].include?(request.method.downcase) # no body to verify
+
+        begin
+          document.ref("#{request_openapi_path}/requestBody")
+        rescue JSONSchemer::InvalidRefPointer
+          # This schema doesn't specify a request body, so don't validate it
+          return false
+        end
+
+        true
+      end
+
+      def document
+        @document ||= JSONSchemer.openapi(open_api_struct)
+      end
+
+      def open_api_struct
+        @open_api_struct ||= load_openapi_file
+      end
+
+      def load_openapi_file
+        YAML.load_file(open_api_filename)
+      end
+
+      attr_reader :open_api_filename
+
+      def open_api_filename=(val)
+        @open_api_struct = nil
+        @document = nil
+        @open_api_filename = val
+      end
+
+      def validate_query_param(spec)
+        result = request.query_parameters[spec["name"]]
+        return unless result
+
+        request.params[spec["name"]] &&= case spec.dig("schema", "type")
+                                         when "boolean"
+                                           ActiveModel::Type::Boolean.new.cast(result)
+                                         else
+                                           result
+                                         end
+      end
+
+      def validate_path_param(spec) # rubocop:disable Metrics/AbcSize
+        result = request.path_parameters[spec["name"].to_sym]
+        ref = spec.dig("schema", "$ref")
+        errors = document.ref(ref).validate(result).to_a
+        raise RequestValidationError, errors.join(", ") unless errors.empty?
+
+        request.params[spec["name"]] = result
+      end
+
+      def request_openapi_path
+        verb = request.method.downcase
+        path = json_ref_for_path
+        "#/paths/#{path}/#{verb}"
+      end
+
+      def json_ref_for_path
+        params = request.path_parameters.except(:controller, :action)
+        path = CGI.unescape(request.path).tr(" ", "+")
+        %i[object_id id].each do |parameter|
+          path.gsub!(params[parameter], "%7B#{parameter}%7D") if params[parameter]
+        end
+        path.gsub("/", "~1")
+      end
+    end
+  end
+end

data/lib/json_schemer/rails/validation_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module JsonSchemer
+  module Rails
+    # Raised when the OpenAPI specification is violated
+    class RequestValidationError < StandardError; end
+  end
+end

data/lib/json_schemer/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module JsonSchemer
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/json_schemer/rails.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "rails/version"
+require_relative "rails/validation_error"
+require_relative "rails/open_api_validator"
+require_relative "rails/controller"
+
+module JsonSchemer
+  module Rails
+    class Error < StandardError; end
+    # Your code goes here...
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: json_schemer-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Justin Coyne
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Rails integration for JsonSchemer. Validates OpenAPI
+email:
+- jcoyne@justincoyne.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/json_schemer/rails.rb
+- lib/json_schemer/rails/controller.rb
+- lib/json_schemer/rails/open_api_validator.rb
+- lib/json_schemer/rails/validation_error.rb
+- lib/json_schemer/rails/version.rb
+homepage: https://github.com/sul-dlss/json_schemer-rails
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/sul-dlss/json_schemer-rails
+  source_code_uri: https://github.com/sul-dlss/json_schemer-rails
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Rails integration for JsonSchemer. Validates OpenAPI
+test_files: []