Merge pull request #3 from SiloGecho97/feat/call-validator-conditional

feat: add request and response schema validator conditionally

Author: SiloGecho97

.gitignore

@@ -30,3 +30,4 @@
 
 # Ignore master key for decrypting credentials and more.
 /config/master.key
+.byebug_history

Gemfile

@@ -40,7 +40,7 @@ gem "scalar_ruby", "~> 1.1"
 group :development, :test do
   # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
   gem "debug", platforms: %i[ mri windows ], require: "debug/prelude"
-
+  gem "byebug"
   # Static analysis for security vulnerabilities [https://brakemanscanner.org/]
   gem "brakeman", require: false
 

Gemfile.lock

@@ -83,6 +83,7 @@ GEM
     brakeman (7.0.0)
       racc
     builder (3.3.0)
+    byebug (11.1.3)
     committee (5.5.1)
       json_schema (~> 0.14, >= 0.14.3)
       openapi_parser (~> 2.0)
@@ -304,6 +305,7 @@ PLATFORMS
 DEPENDENCIES
   bootsnap
   brakeman
+  byebug
   committee
   debug
   kamal

README.md

@@ -1,24 +1,41 @@
-# README
+# Documentation first API development
 
-This README would normally document whatever steps are necessary to get the
-application up and running.
+### What is Documentation-First Approach and its Benefits
 
-Things you may want to cover:
+The documentation-first approach, also known as design-first or API-first, emphasizes creating API documentation before writing any code.The documentation itself acts as a specification.
 
-* Ruby version
+### Benefits of Documentation-First Approach
 
-* System dependencies
+- **Clarity and Communication**: By documenting the API first, all team members, including developers, testers, and business stakeholders, have a clear understanding of the API's purpose and functionality.
+- **Early Feedback**: Documentation can be reviewed and validated by stakeholders before any code is written, allowing for early detection of potential issues or misunderstandings.
+- **Consistency**: Ensures that the implementation adheres strictly to the agreed-upon design, reducing the risk of discrepancies between the documentation and the actual API.
+- **Improved Collaboration**: Facilitates better collaboration between different teams (e.g., frontend and backend) as they can work from a shared, well-defined API specification.
+- **Better Testing**: Test cases can be derived from the documentation, ensuring comprehensive test coverage and validation against the specified API behavior.
+- **Ease of Maintenance**: Having a well-documented API makes it easier to maintain and update, as changes can be tracked and communicated effectively through the documentation.
 
-* Configuration
+By adopting a documentation-first approach, teams can create more reliable, understandable, and maintainable APIs, ultimately leading to better software quality and user satisfaction.
 
-* Database creation
+### OpenAPI Specification
 
-* Database initialization
+The OpenAPI Specification (OAS) is a standard for defining and describing RESTful APIs. It allows both humans and computers to understand the capabilities of a service without accessing its source code or documentation.
 
-* How to run the test suite
+OpenAPI uses a different specification: JSON Schema. This can be used to validate JSON even outside OpenAPI, and it’s a great tool; it’s really readable and easy to understand, but it’s a bit verbose. To fix that, we can use references:
 
-* Services (job queues, cache servers, search engines, etc.)
+e.g., OpenAPI schema: [Petstore Example](https://petstore3.swagger.io/#/)
 
-* Deployment instructions
+### Gem Used: `committee`
 
-* ...
+We used the `committee` gem for our API documentation and validation. It helps in ensuring that our API conforms to the OpenAPI specification.
+
+Altenative gem : [Skooma](https://github.com/skryukov/skooma), [Open-api-first](https://github.com/ahx/openapi_first)
+
+### Non Breaking change
+
+- Add headers to requests, only do validation if headers persent
+  This is how the request validation added
+- For non-breaking changes, instead of returning errors, we log the errors. This approach helps in maintaining the stability of the API while still capturing any issues that need to be addressed.
+  - this is how the response validation added
+
+### Documenation UI
+
+Scalar is add for open api schema UI

config/application.rb

@@ -5,7 +5,8 @@
 # Require the gems listed in Gemfile, including any gems
 # you've limited to :test, :development, or :production.
 Bundler.require(*Rails.groups)
-
+require_relative "../lib/open_api_schema/request_validator_middleware"
+require_relative "../lib/open_api_schema/response_validator_middleware"
 module PocDocsFirst
   class Application < Rails::Application
     # Initialize configuration defaults for originally generated Rails version.
@@ -29,12 +30,9 @@ class Application < Rails::Application
     # Skip views, helpers and assets when generating a new resource.
     config.api_only = true
 
-    config.middleware.use Committee::Middleware::RequestValidation,
-      schema_path: "docs/openapi.json",
-      coerce_date_times: true,
-      params_key: "action_dispatch.request.request_parameters",
-      query_hash_key: "action_dispatch.request.query_parameters",
-      strict_reference_validation: true
-    config.middleware.use Committee::Middleware::ResponseValidation, schema_path: "docs/openapi.json", strict_reference_validation: true
+    # Add the request and response validation middleware to the application.
+    # TODO: This can be changed later to add middleware in exact position e.g config.middleware.after Rack::Runtime, OpenApiSchema::RequestValidatorMiddleware
+    config.middleware.use ::OpenApiSchema::RequestValidatorMiddleware
+    config.middleware.use ::OpenApiSchema::ResponseValidatorMiddleware
   end
 end

lib/open_api_schema/request_validator_middleware.rb

@@ -0,0 +1,31 @@
+
+module OpenApiSchema
+  class RequestValidatorMiddleware
+    def initialize(app)
+      @app = app
+      @request_validator = Committee::Middleware::RequestValidation.new(app, schema_path: "docs/openapi.json", strict_reference_validation: true,  coerce_date_times: true,  params_key: "action_dispatch.request.request_parameters", query_hash_key: "action_dispatch.request.query_parameters")
+    end
+
+    # Handles the middleware call to validate the schema if the "VALIDATE_SCHEMA" header is present.
+    # If the header VALIDATE_SCHEMA is exist, it validates the request schema.
+    #
+    # @param env [Hash] The Rack environment hash.
+    # @return [Array] The status, headers, and response.
+    def call(env)
+      status, headers, response = @app.call(env)
+
+
+      if condition_for_request_validation?(env)
+        status, headers, response = @request_validator.call(env)
+      end
+
+      [ status, headers, response ]
+    end
+
+    private
+
+    def condition_for_request_validation?(env)
+      env.key?("HTTP_VALIDATE_SCHEMA")
+    end
+  end
+end

lib/open_api_schema/response_validator_middleware.rb

@@ -0,0 +1,31 @@
+
+module OpenApiSchema
+  class ResponseValidatorMiddleware
+    # Initializes the middleware with the given Rack application and sets up the response validator.
+    #
+    # @param app [Object] The Rack application.
+    def initialize(app)
+      @app = app
+      @response_validator = Committee::Middleware::ResponseValidation.new(app, schema_path: "docs/openapi.json", strict_reference_validation: true)
+    end
+
+    # Sets up the middleware to validate the response schema if the "VALIDATE_SCHEMA" header is present.
+    #
+    # @param env [Hash] The Rack environment hash.
+    # @return [Array] The status, headers, and response.
+    def call(env)
+      status, headers, response = @app.call(env)
+
+      if condition_for_response_validation?(env)
+        status, headers, response = @response_validator.call(env)
+      end
+
+      [ status, headers, response ]
+    end
+
+    private
+    def condition_for_response_validation?(env)
+      env.key?("HTTP_VALIDATE_SCHEMA")
+    end
+  end
+end