apicraft-rails 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 985bb9a26327f539fba9cfde3fecaab346e445100d32549bab4e393d6656d8b6
-  data.tar.gz: 9df0525f057680a45d18dd5ce899f0151e09366d62ab3b190e895c473e79f4d8
+  metadata.gz: b30ecb65e234276a9d0af7dca63778397b8e1873a1a6a062b92853e791b980ba
+  data.tar.gz: da1c7cffc242a5008aa0166ae6ac874a4f6739def0d928c3e5417361c492cbbf
 SHA512:
-  metadata.gz: '078e7d785cdeb7f95b36984e57dbf8616e2f12832d0b272e589d28f2e1a20ab8dee73f8775ae270ac0293f8b8d974a726d58934adf5bd4308b616fcfbbb69e96'
-  data.tar.gz: 571165414ba898067e3b1d28c9daa0aacb20d8ddb350ac425ea6ac9198066bfe90844a25df3bd2fe47f077c0df1b0a1fa087b2e56f4db62602f5bc225eee8e84
+  metadata.gz: be09f4dd790950e1857c8cec15e945eac4058ac891de58fd8218a3b4c3cf033df314ccc951197235e2a5f5045cf30ef2b5e751acb42fb1988c9eabd1bd6a344c
+  data.tar.gz: 11da384ef306df936c9e1d288552da41001f6c4c7084617f76c0dfaf3edb85312bb22bf21914bd9e034cf36935bc5b79320e9c201f7e10f3a7a9c5db398e1dbe

data/README.md

@@ -1,6 +1,6 @@
 # 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://d25lcipzij17d.cloudfront.net/badge.png?id=rb&r=r&ts=1683906897&type=3e&v=1.0.1&x2=0)](https://badge.fury.io/rb/apicraft-rails)
+[![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.png?id=rb&r=r&ts=1683906897&type=3e&v=1.0.2&x2=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.
 
@@ -14,8 +14,6 @@ It avoids the pitfalls of the code-first methodology, where contracts are auto-g
 
 - [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)
@@ -24,6 +22,7 @@ It avoids the pitfalls of the code-first methodology, where contracts are auto-g
     - [🎮 Behaviour Mocking](#-behaviour-mocking)
     - [🧐 Introspection](#-introspection)
     - [📖 Documentation (Swagger docs and RapiDoc)](#-documentation-swagger-docs-and-rapidoc)
+    - [📖 CLI Support](#-cli-support)
   - [🔧 Configuration](#-configuration)
   - [🤝 Contributing](#-contributing)
   - [📝 License](#-license)
@@ -42,13 +41,7 @@ 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
-- 💎 **Clean & Custom Ruby DSL** - Support for a Ruby DSL alongwith the current `.json` and `.yaml` formats.
-
-
-## 🪄 Works Like Magic
-
-Once you’ve installed the gem, getting started is a breeze. Simply create your OpenAPI contracts within the `app/contracts` directory of your Rails application. You’re free to organize this directory in a way that aligns with your project's standards and preferences. That’s it—your APIs will be up and running with mock responses, ready for development without any additional setup. It's as effortless as it sounds!
+- 🗂 **CLI Support** - Specification validations can be triggered from the CLI allowing integrations into your CI/CD pipelines.
 
 ## 🕊 API Design First Philosophy
 
@@ -71,41 +64,38 @@ By adopting an API Design First approach with APICraft Rails, you can accelerate
 
 ## 🏗 Installation
 
-Add this line to your application's Gemfile:
+1. Add this line to your application's Gemfile:
 
 ```ruby
-gem 'apicraft-rails', '~> 1.0.1'
+gem 'apicraft-rails', '~> 1.0.2'
 ```
 
-And then execute:
+2. And then execute:
+```bash
+$ bundle install
+$ rails apicraft:init
+```
 
-    $ bundle install
+This will create a file called `config/initializers/apicraft.rb` with all the necessary configurations. It will also create the default contracts directory called `app/contracts`.
 
-After the installation in your rails project, you can start adding contracts in the `app/contracts` directory. This can have any internal directory structure based on your API versions, standards, etc.
 
-Add the following into your Rails application, via the `config/application.rb`
+3. Add the `apicraft` route to your route file (for documentation):
 
 ```ruby
-# config/application.rb
-module App
-  class Application < Rails::Application
-    # Rest of the configuration...
-
-    [
-      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")
-    end
-  end
+Rails.application.routes.draw do
+  # other routes
+  mount Apicraft::Web::App, at: "/apicraft"
 end
 ```
 
 Now every API in the specification has a functional version. For any path (from the contracts), APICraft serves a mock response when `Apicraft-Mock: true` is passed in the headers otherwise, it forwards the request to your application as usual.
 
+4. Generate a sample spec file
+```
+rails apicraft:generate file=v2/openapi
+```
+
+This will generate a sample file called `app/contracts/v2/openapi.yaml`
 ## ⚙️ Usage
 
 Add your specification files to the `app/contracts` directory in your Rails project. You can also configure this directory to be something else.
@@ -199,9 +189,7 @@ Example: `https://yoursite.com/api/orders`
       }
     }
   ],
-  "responses": {
-    ...
-  }
+  "responses": {}
 }
 ```
 ### 📖 Documentation (Swagger docs and RapiDoc)
@@ -238,6 +226,17 @@ RapiDoc                    |  SwaggerDoc
 :-------------------------:|:-------------------------:
 ![](assets/rapidoc.png)  |  ![](assets/swaggerdoc.png)
 
+### 📖 CLI Support
+
+To check if all the specification are valid
+```
+$ rails apicraft:validate
+```
+
+To generate a new spec file in the contracts directory
+```
+$ rails apicraft:generate file=openapi
+```
 ## 🔧 Configuration
 
 List of available configurations.

data/lib/apicraft/config.rb

@@ -43,6 +43,10 @@ module Apicraft
       @opts[:contracts_path]
     end
 
+    def default_contracts_path
+      Rails.root.join("app", "contracts")
+    end
+
     def mocks
       @opts[:mocks]
     end

data/lib/apicraft/loader.rb

@@ -38,7 +38,8 @@ module Apicraft
       OpenAPIParser.parse(
         parsed,
         {
-          strict_reference_validation: config.strict_reference_validation
+          strict_reference_validation: config.strict_reference_validation,
+          expand_reference: true
         }
       )
 

data/lib/apicraft/railtie.rb

@@ -4,8 +4,22 @@ module Apicraft
   # Hooks into the application boot process
   # using Rails::Railtie
   class Railtie < Rails::Railtie
-    initializer "apicraft.load_api_contracts" do
+    initializer "apicraft.use_middlewares" do
+      [
+        Apicraft::Middlewares::Mocker,
+        Apicraft::Middlewares::Introspector,
+        Apicraft::Middlewares::RequestValidator
+      ].each { |mw| Rails.application.config.middleware.use mw }
+    end
+
+    config.after_initialize do
       Apicraft::Loader.load!
     end
+
+    rake_tasks do
+      load "apicraft/tasks/validate.rake"
+      load "apicraft/tasks/init.rake"
+      load "apicraft/tasks/generate.rake"
+    end
   end
 end

data/lib/apicraft/tasks/generate.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+namespace :apicraft do
+  desc "Generate an example spec file"
+
+  task generate: :environment do |_t, _args|
+    arguments = ARGV.reduce({}) do |final, current|
+      key, val = current.split("=").map(&:strip)
+      final.merge!({
+                     key => val
+                   })
+    end
+
+    filepath = arguments["file"]
+    template = File.expand_path("../templates/openapi.example.yaml", __dir__)
+
+    # root path of all contracts
+    contracts_path = Apicraft.config.contracts_path
+
+    # Split the filepath into parts to extract the directory structure and file name
+    path_parts = filepath.split("/")
+    dir_path = File.join(contracts_path, *path_parts[0..-2])
+    file_name = "#{path_parts[-1]}.yaml"
+
+    # Create the directory if it doesn't exist
+    FileUtils.mkdir_p(dir_path) unless Dir.exist?(dir_path)
+
+    File.write(File.join(dir_path, file_name), File.read(template))
+  end
+end

data/lib/apicraft/tasks/init.rake

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+namespace :apicraft do
+  desc "Initialize apicraft"
+  task init: :environment do
+    # Setup the apicraft initializer
+    destination = Rails.root.join("config", "initializers", "apicraft.rb")
+    if File.exist?(destination)
+      puts "File already exists: #{destination}"
+    else
+      template = File.expand_path("../templates/initializer.rb", __dir__)
+      FileUtils.cp(template, destination)
+      puts "Apicraft initializer created at config/initializers/apicraft.rb"
+    end
+
+    # Create the default contracts directory
+    contracts_path = Apicraft.config.default_contracts_path
+    FileUtils.mkdir_p(contracts_path) unless Dir.exist?(contracts_path)
+  end
+end

data/lib/apicraft/tasks/validate.rake

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+namespace :apicraft do
+  desc "Validate all contracts"
+  task validate: :environment do
+    Apicraft::Validator.validate!
+  end
+end

data/lib/apicraft/templates/initializer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+Apicraft::Web::App.use do |user, password|
+  [user, password] == %w[admin password]
+end
+
+Apicraft.configure do |config|
+  config.contracts_path = Rails.root.join("app", "contracts")
+
+  # Enables or disables the mocking features
+  # Defaults to true
+  config.mocks = true
+
+  # Enables or disables the introspection features
+  # Defaults to true
+  config.introspection = true
+
+  # allows you to enforce stricter validation of $ref
+  # references in your OpenAPI specifications.
+  # When this option is enabled, the parser will raise
+  # an error if any $ref references in your OpenAPI
+  # document are invalid, ensuring that all references
+  # are correctly defined and resolved.
+  # 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 = 0
+
+  config.headers = {
+    # The name of the header used to control
+    # the response code of the mock
+    # Defaults to Apicraft-Response-Code
+    response_code: "Apicraft-Response-Code",
+
+    # The name of the header to introspect the API.
+    # Defaults to Apicraft-Introspect
+    introspect: "Apicraft-Introspect",
+
+    # The name of the header to mock the API.
+    # Defaults to 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/templates/openapi.example.yaml

@@ -0,0 +1,66 @@
+openapi: 3.0.0
+info:
+  title: Sample API
+  version: 1.0.0
+  description: API template to manage users.
+
+servers:
+  - url: https://api.example.com
+
+paths:
+  /users:
+    get:
+      summary: Get a list of users
+      responses:
+        '200':
+          description: A list of users
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+    post:
+      summary: Create a new user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/User'
+      responses:
+        '201':
+          description: User created successfully
+
+  /users/{id}:
+    get:
+      summary: Get a user by id
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A user object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
+      required:
+        - id
+        - name
+        - email

data/lib/apicraft/validator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Apicraft
+  # Recursively loads and processes YAML files from the
+  # application's contract folder during the application boot.
+  # This class is responsible for loading and initializing the
+  # contracts defined in the YAML files.
+  class Validator
+    def self.validate!
+      contracts_path = Apicraft.config.contracts_path
+      raise Errors::InvalidContractsPath if contracts_path.blank? || !Dir.exist?(contracts_path)
+
+      Find.find(contracts_path) do |path|
+        next unless File.file?(path) && %w[.yaml .yml .json].include?(File.extname(path))
+
+        validate_file!(path)
+      end
+    end
+
+    def self.validate_file!(file)
+      ext = File.extname(file)
+
+      parsed = if ext == ".json"
+                 JSON.parse(File.read(file))
+               else
+                 YAML.load_file(file)
+               end
+
+      OpenAPIParser.parse(
+        parsed,
+        {
+          strict_reference_validation: config.strict_reference_validation
+        }
+      )
+    end
+
+    def self.config
+      Apicraft.config
+    end
+  end
+end

data/lib/apicraft/version.rb

@@ -2,5 +2,5 @@
 
 # Current version of Apicraft.
 module Apicraft
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/lib/apicraft-rails.rb

@@ -19,6 +19,7 @@ require_relative "apicraft/errors"
 require_relative "apicraft/mocker"
 require_relative "apicraft/openapi"
 
+require_relative "apicraft/validator"
 require_relative "apicraft/loader"
 require_relative "apicraft/railtie"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apicraft-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Abhishek Sarkar
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-12 00:00:00.000000000 Z
+date: 2024-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -151,6 +151,12 @@ files:
 - lib/apicraft/openapi/operation.rb
 - lib/apicraft/openapi/response.rb
 - lib/apicraft/railtie.rb
+- lib/apicraft/tasks/generate.rake
+- lib/apicraft/tasks/init.rake
+- lib/apicraft/tasks/validate.rake
+- lib/apicraft/templates/initializer.rb
+- lib/apicraft/templates/openapi.example.yaml
+- lib/apicraft/validator.rb
 - lib/apicraft/version.rb
 - lib/apicraft/web.rb
 - lib/apicraft/web/actions.rb