apicraft-rails 0.5.1.beta1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03c78edc81f87417dfdd7411be50609da4d39bb0827775ea16b609cce641a7bd
-  data.tar.gz: 652eb5761da35bc28f8a779015c74ef0b971d94231250aa02edcd3c3ff1cc7b3
+  metadata.gz: 7692b6e9a2cd444c2f5db48a932c78d64e4a23172575cafb76ed307c527c1ed3
+  data.tar.gz: 120c7cf23160c70761a168a815704bbcafc2e1c87901d5b2c58c037c840c4151
 SHA512:
-  metadata.gz: fe96cef636e07bc57e26ff11401e315ab457783cf254f33de98ec233a8f2c4b72be7c4b4f593f023deb615b17ce5166f8309fabc6a298139913d58e478363489
-  data.tar.gz: f23638693ebe922a7de1b98bfef20f7cad9777704c21603489ffe6677afc33ec9020173a2cfdb76dd59c52e7246a42dbb55fcd2443f9ff7fa4946a6764c84dd6
+  metadata.gz: dfe9dc9efc333d44b43825b5f0b5a3377ffdb1e3016a725c131b923ac15be131b5e8bc5e1ad6dc06cfd58ccc7ae493cf18b0c54846507491828550c884657e0b
+  data.tar.gz: a9bb65b6c85b07e5a17c52b99bcf59435cff0810191358b214fdd45bbea8cb5e181f5d7e1332431b74c9473f6a6a531e063e9391500eef78fad67b2b2d197231

data/README.md

@@ -1,6 +1,6 @@
-# APICraft Rails (Beta)
+# APICraft Rails
 [![Build](https://github.com/apicraft-dev/apicraft-rails/actions/workflows/build.yml/badge.svg)](https://github.com/apicraft-dev/apicraft-rails/actions/workflows/build.yml)
-[![Gem Version](https://badge.fury.io/rb/apicraft-rails.svg)](https://badge.fury.io/rb/apicraft-rails)
+[![Gem Version](https://badge.fury.io/rb/apicraft-rails.svg?v=1.0.0)](https://badge.fury.io/rb/apicraft-rails)
 
 🚀 Accelerates your development by 2-3x with an API Design First approach. Seamlessly integrates with your Rails application server — no fancy tooling or expenses required.
 
@@ -12,23 +12,26 @@ It avoids the pitfalls of the code-first methodology, where contracts are auto-g
 
 ![APICraft Rails Logo](assets/apicraft_rails.png)
 
-- [APICraft Rails (Beta)](#apicraft-rails-beta)
+- [APICraft Rails](#apicraft-rails)
   - [✨ Features](#-features)
   - [🔜 Upcoming Features](#-upcoming-features)
   - [🪄 Works Like Magic](#-works-like-magic)
   - [🕊 API Design First Philosophy](#-api-design-first-philosophy)
   - [🏗 Installation](#-installation)
   - [⚙️ Usage](#️-usage)
-    - [🎭 API Mocking](#-api-mocking)
-    - [🎮 API Mocking (Behaviours)](#-api-mocking-behaviours)
-    - [🧐 API Introspection](#-api-introspection)
-    - [📖 API Documentation (Swagger docs and RapiDoc)](#-api-documentation-swagger-docs-and-rapidoc)
+    - [🛡️ Request Validations](#️-request-validations)
+    - [🎭 Mocking](#-mocking)
+    - [🎮 Behaviour Mocking](#-behaviour-mocking)
+    - [🧐 Introspection](#-introspection)
+    - [📖 Documentation (Swagger docs and RapiDoc)](#-documentation-swagger-docs-and-rapidoc)
   - [🔧 Configuration](#-configuration)
   - [🤝 Contributing](#-contributing)
   - [📝 License](#-license)
   - [📘 Code of Conduct](#-code-of-conduct)
 
 ## ✨ Features
+- 🛡️ **Automatic Request Validations** - Validates the request based on the openapi specs so that you don't need to add params validations everywhere in your controllers.
+
 - 🧑‍💻️ **Dynamic Mock Data Generation** - Detects the specifications and instantly mounts working routes with mock responses. No extra configuration required.
 
 - ⚙️ **Customizable Mock Responses** - Tailor mock responses to simulate different scenarios and edge cases, helping your team prepare for real-world conditions right from the start.
@@ -40,7 +43,6 @@ It avoids the pitfalls of the code-first methodology, where contracts are auto-g
 - 🗂 **Easy Contracts Management** - Management of `openapi` specifications from within `app/contracts` directory. No new syntax, just plain old `openapi` standard with `.json` or `.yaml` formats
 
 ## 🔜 Upcoming Features
-- 💢 **Request Validations** - Automatic request validations.
 - 💎 **Clean & Custom Ruby DSL** - Support for a Ruby DSL alongwith the current `.json` and `.yaml` formats.
 
 
@@ -72,7 +74,7 @@ By adopting an API Design First approach with APICraft Rails, you can accelerate
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'apicraft-rails', '~> 0.5.1.beta1'
+gem 'apicraft-rails', '~> 1.0.0'
 ```
 
 And then execute:
@@ -89,8 +91,11 @@ module App
   class Application < Rails::Application
     # Rest of the configuration...
 
-    config.middleware.use Apicraft::Middlewares::Mocker
-    config.middleware.use Apicraft::Middlewares::Introspector
+    [
+      Apicraft::Middlewares::Mocker,
+      Apicraft::Middlewares::Introspector,
+      Apicraft::Middlewares::RequestValidator
+    ].each { |mw| config.middleware.use mw }
 
     Apicraft.configure do |config|
       config.contracts_path = Rails.root.join("app/contracts")
@@ -117,7 +122,11 @@ my_rails_app/
 │   │   ├── user.rb
 │   │   └── order.rb
 ```
-### 🎭 API Mocking
+
+### 🛡️ Request Validations
+All incoming requests will be validated against the defined schema. This ensures that by the time the params reach the controller they are adhering to all the schema requirements. It's enabled by default. You can customize the response of a failed validation. Check the [configuration section](#-configuration) section for a full list of options for this.
+
+### 🎭 Mocking
 **APICraft** dynamically generates mock APIs by interpreting contract specifications on the fly. You can request the mock response by passing `Apicraft-Mock: true` in the headers.
 
 `https://yoursite.com/api/orders`
@@ -141,14 +150,16 @@ headers: {
 ]
 ```
 
-### 🎮 API Mocking (Behaviours)
+### 🎮 Behaviour Mocking
 The above is an example of a 200 response. If you have more responses documented you can force that behaviour using `Apicraft-Response-Code` header in the mock request.
+You can find a list of all the supported headers in the [configuration section](#-configuration) that would allow you to manipulate the API Behaviour.
 
 `https://yoursite.com/api/orders`
 ```
 headers: {
   Apicraft-Response-Code: 400
   Apicraft-Mock: true
+  Apicraft-Delay: 5
 }
 ```
 ```json
@@ -158,12 +169,12 @@ headers: {
 }
 ```
 
-### 🧐 API Introspection
-All APIs are can be introspected. You can do so by passing the `Apicraft-Introspection` header.
+### 🧐 Introspection
+All APIs are can be introspected. You can do so by passing the `Apicraft-Introspect` header.
 
 ```
 headers: {
-  Apicraft-Introspection: true
+  Apicraft-Introspect: true
 }
 ```
 
@@ -193,7 +204,7 @@ Example: `https://yoursite.com/api/orders`
   }
 }
 ```
-### 📖 API Documentation (Swagger docs and RapiDoc)
+### 📖 Documentation (Swagger docs and RapiDoc)
 
 Mount the documentation views in your route file.
 
@@ -223,6 +234,9 @@ module App
   end
 end
 ```
+RapiDoc                    |  SwaggerDoc
+:-------------------------:|:-------------------------:
+![](assets/rapidoc.png)  |  ![](assets/swaggerdoc.png)
 
 ## 🔧 Configuration
 
@@ -249,6 +263,10 @@ Apicraft.configure do |config|
   # Defaults to true
   config.strict_reference_validation = true
 
+  # When simulating delay using the mocks, the max
+  # delay in seconds that can be simulated
+  config.max_allowed_delay = 30
+
   config.headers = {
     # The name of the header used to control
     # the response code of the mock
@@ -257,11 +275,28 @@ Apicraft.configure do |config|
 
     # The name of the header to introspect the API.
     # Defaults to Apicraft-Introspect
-    introspect: "Apicraft-Introspect"
+    introspect: "Apicraft-Introspect",
 
     # The name of the header to mock the API.
     # Defaults to Apicraft-Mock
-    mock: "Apicraft-Mock"
+    mock: "Apicraft-Mock",
+
+    # Delay simulation header name
+    delay: "Apicraft-Delay"
+  }
+
+  config.request_validation = {
+    enabled: true,
+
+    # Return the http code for validation errors, defaults to 400
+    http_code: 400,
+
+    # Return a custom response body, defaults to `{ message: "..." }`
+    response_body: proc do |ex|
+      {
+        message: ex.message
+      }
+    end
   }
 end
 

data/lib/apicraft/concerns/middleware_util.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Apicraft
+  module Concerns
+    # Helper class with shared methods
+    module MiddlewareUtil
+      def config
+        @config ||= Apicraft.config
+      end
+
+      def convertor(format)
+        return if format.blank?
+
+        Apicraft::Constants::MIME_TYPE_CONVERTORS[format]
+      end
+    end
+  end
+end

data/lib/apicraft/concerns.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "concerns/cacheable"
+require_relative "concerns/middleware_util"
 
 module Apicraft
   # Namespace module for Concerns

data/lib/apicraft/config.rb

@@ -13,18 +13,22 @@ module Apicraft
         response_code: "Apicraft-Response-Code",
         introspect: "Apicraft-Introspect",
         mock: "Apicraft-Mock",
+        delay: "Apicraft-Delay",
         content_type: "Content-Type"
       },
       mocks: true,
       introspection: true,
       strict_reference_validation: true,
-      request_validations: true
+      max_allowed_delay: 30,
+      request_validation: {
+        enabled: true,
+        http_code: 400,
+        response_body: proc { |ex| { message: ex.message } }
+      }
     }.with_indifferent_access
 
-    def initialize(opts = {})
-      @opts = DEFAULTS.merge(
-        opts
-      ).with_indifferent_access
+    def initialize
+      @opts = DEFAULTS
     end
 
     def headers
@@ -47,6 +51,26 @@ module Apicraft
       @opts[:introspection]
     end
 
+    def max_allowed_delay
+      @opts[:max_allowed_delay]
+    end
+
+    def request_validation
+      @opts[:request_validation]
+    end
+
+    def request_validation_enabled?
+      @opts[:request_validation][:enabled]
+    end
+
+    def request_validation_http_code
+      @opts[:request_validation][:http_code] || DEFAULTS[:request_validation][:http_code]
+    end
+
+    def request_validation_response_body
+      @opts[:request_validation][:response_body]
+    end
+
     def contracts_path=(contracts_path)
       @opts[:contracts_path] = contracts_path
     end
@@ -63,8 +87,14 @@ module Apicraft
       @opts[:strict_reference_validation] = enabled
     end
 
-    def request_validations=(enabled)
-      @opts[:request_validations] = enabled
+    def request_validation=(request_validation_opts)
+      @opts[:request_validation] = @opts[:request_validation].merge(
+        request_validation_opts.with_indifferent_access
+      )
+    end
+
+    def max_allowed_delay=(enabled)
+      @opts[:max_allowed_delay] = enabled
     end
 
     def headers=(headers)

data/lib/apicraft/errors.rb

@@ -7,5 +7,6 @@ module Apicraft
     class InvalidContract < StandardError; end
     class InvalidOperation < StandardError; end
     class InvalidResponse < StandardError; end
+    class DelayTooHigh < StandardError; end
   end
 end

data/lib/apicraft/middlewares/introspector.rb

@@ -4,6 +4,8 @@ module Apicraft
   module Middlewares
     # Apicraft Middleware to handle API Introspection.
     class Introspector
+      include Concerns::MiddlewareUtil
+
       def initialize(app)
         @app = app
       end
@@ -30,10 +32,6 @@ module Apicraft
 
       private
 
-      def config
-        @config ||= Apicraft.config
-      end
-
       def introspect?(request)
         request.headers[config.headers[:introspect]].present?
       end

data/lib/apicraft/middlewares/mocker.rb

@@ -5,6 +5,8 @@ module Apicraft
     # Apicraft Middleware to handle routing
     # and make mock calls available.
     class Mocker
+      include Concerns::MiddlewareUtil
+
       def initialize(app)
         @app = app
       end
@@ -15,28 +17,15 @@ module Apicraft
         request = ActionDispatch::Request.new(env)
         return @app.call(env) unless mock?(request)
 
-        contract = Apicraft::Openapi::Contract.find_by_operation(
-          request.method, request.path_info
-        )
-        raise Errors::InvalidContract if contract.blank?
-
-        operation = contract.operation(
-          request.method, request.path_info
-        )
-        raise Errors::InvalidOperation if operation.blank?
+        use_delay!(request)
+        contract = find_contract!(request)
+        operation = find_operation!(contract, request)
 
         code = request.headers[config.headers[:response_code]] || "200"
         response = operation.response_for(code.to_s)
         raise Errors::InvalidResponse if response.blank?
 
-        # Determine the format passed in the request.
-        # If passed we use it and the response format.
-        # If not we use the first format from the specs.
-        request.format.to_s
-        # indicates that not format was specified.
-        format = nil
-
-        content, content_type = response.mock(format)
+        content, content_type = response.mock(request.content_type)
 
         [
           code.to_i,
@@ -51,18 +40,37 @@ module Apicraft
 
       private
 
-      def config
-        @config ||= Apicraft.config
+      def mock?(request)
+        request.headers[config.headers[:mock]].present?
       end
 
-      def convertor(format)
-        return if format.blank?
+      def find_contract!(request)
+        contract = Apicraft::Openapi::Contract.find_by_operation(
+          request.method, request.path_info
+        )
+        raise Errors::InvalidContract if contract.blank?
 
-        Apicraft::Constants::MIME_TYPE_CONVERTORS[format]
+        contract
       end
 
-      def mock?(request)
-        request.headers[config.headers[:mock]].present?
+      def find_operation!(contract, request)
+        operation = contract.operation(
+          request.method, request.path_info
+        )
+        raise Errors::InvalidOperation if operation.blank?
+
+        operation
+      end
+
+      def use_delay!(request)
+        request_delay = delay(request)
+        raise Errors::DelayTooHigh if request_delay > config.max_allowed_delay
+
+        sleep(request_delay)
+      end
+
+      def delay(request)
+        request.headers[config.headers[:delay]].to_i
       end
     end
   end

data/lib/apicraft/middlewares/request_validator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Apicraft
+  module Middlewares
+    # Middleware to handle Request Validation.
+    class RequestValidator
+      include Concerns::MiddlewareUtil
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless validate?
+
+        request = ActionDispatch::Request.new(env)
+        content_type = request.content_type
+
+        operation = Apicraft::Openapi::Contract.find_by_operation(
+          request.method, request.path_info
+        )&.operation(
+          request.method, request.path_info
+        )
+        return @app.call(env) if operation.blank?
+
+        operation.validate_request_body(
+          content_type,
+          request.params
+        )
+        @app.call(env)
+      rescue OpenAPIParser::OpenAPIError => e
+        [
+          config.request_validation_http_code,
+          { 'Content-Type': content_type },
+          [
+            response_body(e)&.send(convertor(content_type))
+          ].compact
+        ]
+      end
+
+      private
+
+      def validate?
+        config.request_validation_enabled?
+      end
+
+      def response_body(ex)
+        config.request_validation_response_body.call(ex)
+      end
+    end
+  end
+end

data/lib/apicraft/middlewares.rb

@@ -2,6 +2,7 @@
 
 require_relative "middlewares/mocker"
 require_relative "middlewares/introspector"
+require_relative "middlewares/request_validator"
 
 module Apicraft
   # Namespace module for Concerns

data/lib/apicraft/openapi/contract.rb

@@ -15,10 +15,10 @@ module Apicraft
       end
 
       def operation(method, path)
-        with_cache("operation-#{method.downcase}-#{path}") do
-          op = document.request_operation(method.downcase, path)
-          Operation.new(op) if op.present?
-        end
+        # with_cache("operation-#{method.downcase}-#{path}") do
+        op = document.request_operation(method.downcase, path)
+        Operation.new(op) if op.present?
+        # end
       end
 
       class << self

data/lib/apicraft/openapi/operation.rb

@@ -8,15 +8,16 @@ module Apicraft
       attr_accessor :operation
 
       def initialize(operation)
-        @operation = operation.operation_object
+        @operation = operation
+        @operation_object = operation.operation_object
       end
 
       def responses
-        @operation.responses
+        @operation_object.responses
       end
 
       def summary
-        @operation.summary
+        @operation_object.summary
       end
 
       def response_for(code)
@@ -29,7 +30,14 @@ module Apicraft
       end
 
       def raw_schema
-        operation.raw_schema
+        @operation_object.raw_schema
+      end
+
+      def validate_request_body(content_type, body)
+        operation.validate_request_body(
+          content_type,
+          body
+        )
       end
     end
   end

data/lib/apicraft/version.rb

@@ -2,5 +2,5 @@
 
 # Current version of Apicraft.
 module Apicraft
-  VERSION = "0.5.1.beta1"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apicraft-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.1.beta1
+  version: 1.0.0
 platform: ruby
 authors:
 - Abhishek Sarkar
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-10 00:00:00.000000000 Z
+date: 2024-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -126,6 +126,7 @@ files:
 - lib/apicraft-rails.rb
 - lib/apicraft/concerns.rb
 - lib/apicraft/concerns/cacheable.rb
+- lib/apicraft/concerns/middleware_util.rb
 - lib/apicraft/config.rb
 - lib/apicraft/constants.rb
 - lib/apicraft/errors.rb
@@ -133,6 +134,7 @@ files:
 - lib/apicraft/middlewares.rb
 - lib/apicraft/middlewares/introspector.rb
 - lib/apicraft/middlewares/mocker.rb
+- lib/apicraft/middlewares/request_validator.rb
 - lib/apicraft/mocker.rb
 - lib/apicraft/mocker/all_of.rb
 - lib/apicraft/mocker/any_of.rb
@@ -183,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: APICraft Rails - Simplified API Design First Development