Merge branch 'main' into add-error-log-for-validator

Author: SiloGecho97

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

@@ -30,6 +30,8 @@ class Application < Rails::Application
     # Skip views, helpers and assets when generating a new resource.
     config.api_only = 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

lib/open_api_schema/request_validator_middleware.rb

@@ -7,8 +7,7 @@ def initialize(app)
     end
 
     # Handles the middleware call to validate the schema if the "VALIDATE_SCHEMA" header is present.
-    # If the header is set to "1", it validates the request schema.
-    # Otherwise, it continues the request-response cycle as usual.
+    # 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.

lib/open_api_schema/response_validator_middleware.rb

@@ -39,7 +39,7 @@ def initialize(app)
       @response_validator = Committee::Middleware::ResponseValidation.new(app, schema_path: "docs/openapi.json",  ignore_error: true, error_handler: error_handler)
     end
 
-    # Handles the middleware call to validate the schema if the "VALIDATE_SCHEMA" header is present.
+    # 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.
@@ -54,7 +54,6 @@ def call(env)
     end
 
     private
-
     def condition_for_response_validation?(env)
      true # env.key?("HTTP_VALIDATE_SCHEMA")
     end