apicraft-rails 0.5.0.beta1 → 0.5.1.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 847b284dc12a51e2364740eef912f4238c771a7e9d143fa7ea63090afca69e03
-  data.tar.gz: 1a2c2c667280415035ca7af8a95de9dbadc2859ee932a65c4890b30f37208821
+  metadata.gz: 03c78edc81f87417dfdd7411be50609da4d39bb0827775ea16b609cce641a7bd
+  data.tar.gz: 652eb5761da35bc28f8a779015c74ef0b971d94231250aa02edcd3c3ff1cc7b3
 SHA512:
-  metadata.gz: 588307957dd26f89f9f661ab36f55ea33d47fd601e4f563481e32a29a526734c8daa8e2c51bd2741ace545a52079549587f7cc720f9c1f84f7187533cf4dd294
-  data.tar.gz: 4a65d260b4f9124733cb1aeb1d069598f0f87ad6e4a6322c0bfa2ba842fdbcca2de626e23fb6dfbcae0340eb8ddb51a4400867e544a278c4fa2dd12c237bfe4b
+  metadata.gz: fe96cef636e07bc57e26ff11401e315ab457783cf254f33de98ec233a8f2c4b72be7c4b4f593f023deb615b17ce5166f8309fabc6a298139913d58e478363489
+  data.tar.gz: f23638693ebe922a7de1b98bfef20f7cad9777704c21603489ffe6677afc33ec9020173a2cfdb76dd59c52e7246a42dbb55fcd2443f9ff7fa4946a6764c84dd6

data/README.md

@@ -1,10 +1,33 @@
 # APICraft Rails (Beta)
 [![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)
 
 🚀 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.
 
+We believe that API contracts should lead the development process, not be an afterthought derived from code. This framework embraces the [**API Design-First philosophy**](#-api-design-first-philosophy), ensuring that contracts remain independent from implementation.
+
+With APICraft, contracts are not only clear and consistent, but they’re also immediately usable, enabling teams to work with automatically generated mocks, behaviours and introspection tools, allowing development to begin in parallel, without waiting for backend implementations.
+
+It avoids the pitfalls of the code-first methodology, where contracts are auto-generated, often leading to inconsistency and misalignment.
+
 ![APICraft Rails Logo](assets/apicraft_rails.png)
 
+- [APICraft Rails (Beta)](#apicraft-rails-beta)
+  - [✨ 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)
+  - [🔧 Configuration](#-configuration)
+  - [🤝 Contributing](#-contributing)
+  - [📝 License](#-license)
+  - [📘 Code of Conduct](#-code-of-conduct)
+
 ## ✨ Features
 - 🧑‍💻️ **Dynamic Mock Data Generation** - Detects the specifications and instantly mounts working routes with mock responses. No extra configuration required.
 
@@ -12,11 +35,13 @@
 
 - 🔍 **API Introspections** - Introspect API schemas without needing to dig into the docs everytime.
 
-- 📺 **Documentation Out of the Box** - Documentation using `SwaggerDoc` and `Redoc` both.
+- 📺 **Documentation Out of the Box** - Documentation using `SwaggerDoc` and `RapiDoc` both.
 
 - 🗂 **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
 
-- 🔜 **Request Validations** - Automatic request validations (coming soon)
+## 🔜 Upcoming Features
+- 💢 **Request Validations** - Automatic request validations.
+- 💎 **Clean & Custom Ruby DSL** - Support for a Ruby DSL alongwith the current `.json` and `.yaml` formats.
 
 
 ## 🪄 Works Like Magic
@@ -42,12 +67,12 @@ The API Design First philosophy is at the heart of APICraft Rails, and it’s a
 By adopting an API Design First approach with APICraft Rails, you can accelerate your development process by 2-3x, delivering high-quality APIs faster and with fewer headaches.
 
 
-## Installation
+## 🏗 Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'apicraft-rails', '~> 0.5.0.beta1'
+gem 'apicraft-rails', '~> 0.5.1.beta1'
 ```
 
 And then execute:
@@ -76,7 +101,7 @@ 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.
 
-## Usage
+## ⚙️ Usage
 
 Add your specification files to the `app/contracts` directory in your Rails project. You can also configure this directory to be something else.
 ```
@@ -92,7 +117,7 @@ my_rails_app/
 │   │   ├── user.rb
 │   │   └── order.rb
 ```
-### 🥷 Working with Mock APIs
+### 🎭 API 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`
@@ -116,6 +141,7 @@ headers: {
 ]
 ```
 
+### 🎮 API Mocking (Behaviours)
 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.
 
 `https://yoursite.com/api/orders`
@@ -132,7 +158,7 @@ headers: {
 }
 ```
 
-### 👀 API Introspection
+### 🧐 API Introspection
 All APIs are can be introspected. You can do so by passing the `Apicraft-Introspection` header.
 
 ```
@@ -167,7 +193,7 @@ Example: `https://yoursite.com/api/orders`
   }
 }
 ```
-### 👀 API Documentation
+### 📖 API Documentation (Swagger docs and RapiDoc)
 
 Mount the documentation views in your route file.
 
@@ -182,7 +208,7 @@ end
 
 You can browse API Documentation at
 - `/apicraft/swaggerdoc`
-- `/apicraft/redoc`
+- `/apicraft/rapidoc`
 
 Enable authentication for the `/apicraft` namespace.
 
@@ -198,7 +224,7 @@ module App
 end
 ```
 
-## Configuration
+## 🔧 Configuration
 
 List of available configurations.
 
@@ -244,14 +270,14 @@ Apicraft::Web::App.use do |user, password|
 end
 ```
 
-## Contributing
+## 🤝 Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/apicraft-dev/apicraft-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/apicraft-dev/apicraft-rails/blob/main/CODE_OF_CONDUCT.md).
 
-## License
+## 📝 License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Code of Conduct
+## 📘 Code of Conduct
 
 Everyone interacting in the Apicraft project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/apicraft/blob/main/CODE_OF_CONDUCT.md).

data/lib/apicraft/version.rb

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

data/lib/apicraft/web/actions.rb

@@ -5,16 +5,11 @@ module Apicraft
     # Web actions to be handled from
     # the rack app.
     module Actions
-      def self.index(view_path)
-        [
-          File.read(view_path),
-          "text/html"
-        ]
-      end
-
-      def self.swaggerdoc(view_path)
+      def self.render_erb(view_path)
         @vars = {
-          urls: Router.contract_urls
+          urls: Router.contract_urls,
+          namespace: Router.namespace,
+          version: Apicraft::VERSION
         }
 
         [
@@ -25,16 +20,10 @@ module Apicraft
         ]
       end
 
-      def self.redoc(view_path)
-        @vars = {
-          urls: Router.contract_urls
-        }
-
+      def self.images(view_path)
         [
-          ERB.new(
-            File.read(view_path)
-          ).result(binding),
-          "text/html"
+          File.read(view_path),
+          mime_type(view_path)
         ]
       end
 
@@ -45,15 +34,9 @@ module Apicraft
         ]
       end
 
-      def self.introspect(method, view_path)
-        [
-          Apicraft::Openapi::Contract.find_by_operation(
-            method, view_path
-          )&.operation(
-            method, view_path
-          )&.raw_schema&.to_json,
-          "application/json"
-        ]
+      def self.mime_type(view_path)
+        ext = File.extname(view_path)
+        Rack::Mime.mime_type(ext)
       end
     end
   end

data/lib/apicraft/web/app.rb

@@ -13,10 +13,10 @@ module Apicraft
         Router.namespace = env["SCRIPT_NAME"]
         path = uri.split(
           Router.namespace
-        )[-1]
+        )[-1] || "/"
 
         content, content_type = Router.load_response!(
-          method, path || "/"
+          method, path
         )
 
         raise Errors::RouteNotFound if content.nil?

data/lib/apicraft/web/router.rb

@@ -7,20 +7,33 @@ module Apicraft
       WEB_ROOT = File.expand_path(
         "#{File.dirname(__FILE__)}/../../../web"
       )
+      IMAGES_DIR = "#{WEB_ROOT}/assets/images"
 
       def self.routes
         @routes ||= {
           "/": {
-            action: :index,
-            view_path: "#{WEB_ROOT}/views/index.html"
+            action: :render_erb,
+            view_path: "#{WEB_ROOT}/views/index.erb"
           },
           "/swaggerdoc": {
-            action: :swaggerdoc,
+            action: :render_erb,
             view_path: "#{WEB_ROOT}/views/swaggerdoc.erb"
           },
           "/redoc": {
-            action: :redoc,
+            action: :render_erb,
             view_path: "#{WEB_ROOT}/views/redoc.erb"
+          },
+          "/rapidoc": {
+            action: :render_erb,
+            view_path: "#{WEB_ROOT}/views/rapidoc.erb"
+          },
+          "/assets/images/thumb.png": {
+            action: :images,
+            view_path: "#{IMAGES_DIR}/apicraft_thumb.png"
+          },
+          "/assets/images/logo.png": {
+            action: :images,
+            view_path: "#{IMAGES_DIR}/apicraft.png"
           }
         }.with_indifferent_access
       end
@@ -32,9 +45,7 @@ module Apicraft
         }
       end
 
-      def self.load_response!(method, path)
-        return Actions.introspect(method, path) unless routes[path].present?
-
+      def self.load_response!(_method, path)
         Actions.send(
           routes[path][:action],
           routes[path][:view_path]

data/web/views/index.erb

@@ -0,0 +1,83 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>APICraft</title>
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+    <style>
+      body {
+        margin: 0;
+        padding-top: 40px;
+        font-family: 'Montserrat', 'Roboto', sans-serif;
+        background-color: #121212;
+        position: relative;
+      }
+      #container {
+        margin-top: 60px;
+        text-align: center;
+        max-width: 550px;
+        margin-left: auto;
+        margin-right: auto;
+        color: white;
+      }
+      .muted {
+        opacity: 0.5;
+      }
+      .primary-btn {
+        background-color: #4C2A85;
+        color: white;
+        padding: 10px 20px;
+        text-decoration: none;
+        border-radius: 5px;
+        font-size: 16px;
+        display: inline-block;
+        cursor: pointer;
+        transition: background-color 0.3s ease;
+      }
+
+      .primary-btn:hover {
+        background-color: #3A2064;
+      }
+
+      .github-btn {
+        background-color: white;
+        color: #4C2A85;
+        padding: 5px 10px;
+        text-decoration: none;
+        border-radius: 5px;
+        font-size: 12px;
+        display: inline-block;
+        border: 2px solid #4C2A85;
+        cursor: pointer;
+        transition: background-color 0.3s ease, color 0.3s ease, box-shadow 0.3s ease;
+        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+      }
+
+      .github-btn:hover {
+        box-shadow: 0 6px 8px rgba(0, 0, 0, 0.15);
+      }
+    </style>
+  </head>
+  <body>
+    <div id="container">
+      <img src="<%= @vars[:namespace] %>/assets/images/logo.png" height="120" width="120"/>
+      <p>Welcome to <strong>API</strong>Craft.<p>
+      <p class="muted">An opinionated framework for an API Design First approach to development.</p>
+      <div>
+        <a class="primary-btn" href="<%= @vars[:namespace] %>/rapidoc">RapiDoc</a>
+        <a class="primary-btn" href="<%= @vars[:namespace] %>/swaggerdoc">Swagger</a>
+      </div>
+      <br/>
+      <div>
+        <a href="https://github.com/apicraft-dev/apicraft-rails" class="github-btn" target="_blank">
+          ⭐ Star us on GitHub
+        </a>
+      </div>
+      <br/>
+      <div>
+        <code class="muted">v<%= @vars[:version] %></code>
+      </div>
+    </div>
+  </body>
+</html>

data/web/views/rapidoc.erb

@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>APICraft - Rapidoc</title>
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+    <style>
+      body {
+        margin: 0;
+        font-family: 'Montserrat', 'Roboto', sans-serif;
+        background-color: #121212;
+      }
+
+      .select-label {
+        color: white;
+        font-weight: 400;
+        margin-right: 10px;
+      }
+
+      #api_select {
+        padding: 16px 16px;
+        color: white;
+        background-color: black;
+        border: none;
+        border-bottom: 1px solid #333;
+        border-radius: 0px;
+        cursor: pointer;
+        outline: none !important;
+        width: 100%;
+        display: none;
+      }
+
+      rapi-doc {
+        flex-grow: 1;
+        height: calc(100vh - 0px); /* Adjust for nav height */
+        width: 100%;
+        display: none;
+      }
+    </style>
+  </head>
+  <body>
+    <rapi-doc
+      theme="dark"
+      id="rapidoc_element"
+      header-color="#121212"
+      primary-color="#4C2A85"
+      use-path-in-nav-bar="false"
+      bg-color="#111"
+      show-header="false"
+    >
+      <div slot="nav-logo">
+        <img
+          src="assets/images/thumb.png"
+          height="60px"
+          width="60px"
+        />
+      <span style="top: -23px; position: relative;"><strong>API</strong>Craft</span>
+      </div>
+      <select id="api_select">
+      </select>
+    </rapi-doc>
+    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+    <script>
+      var $rapiDocElement = document.getElementById('rapidoc_element');
+      var $select = document.getElementById('api_select');
+
+      // List of APIs
+      var apis = <%=
+        @vars[:urls].map do |u|
+          { url: u, name: u.gsub(Apicraft::Web::Router.namespace, "") }
+        end.to_json
+      %>
+
+      $rapiDocElement.setAttribute('spec-url', apis[0].url);
+      $rapiDocElement.setAttribute('style', "display: block;");
+
+      // Function to handle API selection change
+      function onSelectChange() {
+        var url = this.value;
+        $rapiDocElement.setAttribute('spec-url', url);
+      }
+
+      // Dynamically building the select dropdown options
+      apis.forEach(function(api) {
+        var $option = document.createElement('option');
+        $option.setAttribute('value', api.url);
+        $option.innerText = api.name;
+        $select.appendChild($option);
+      });
+
+      // Adding event listener for select dropdown change
+      $select.addEventListener('change', onSelectChange);
+      $select.setAttribute('style', "display: block;");
+    </script>
+    <style>
+      .header-title {
+        display: none !important;
+      }
+    </style>
+  </body>
+</html>

data/web/views/redoc.erb

@@ -60,8 +60,32 @@
         end.to_json
       %>
 
+      const customTheme = {
+        colors: {
+          primary: {
+            main: '#4CAF50', // Set the primary color to #4CAF50
+          },
+          text: {
+            primary: '#ffffff',
+            secondary: '#b0b0b0',
+          },
+          background: {
+            primary: '#1a1a1a', // Set the background color to #1a1a1a
+            secondary: '#222222',
+          },
+          borders: '#4CAF50', // Border color for primary sections
+        },
+        typography: {
+          fontSize: '16px',
+          fontFamily: '"Montserrat", "Roboto", sans-serif',
+        },
+        sidebar: {
+          backgroundColor: '#2b2b2b',
+        },
+      };
+
       // Initially render first API
-      Redoc.init(apis[0].url);
+      Redoc.init(apis[0].url, { theme: null });
 
       // Function to handle API selection change
       function onSelectChange() {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apicraft-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0.beta1
+  version: 0.5.1.beta1
 platform: ruby
 authors:
 - Abhishek Sarkar
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-08 00:00:00.000000000 Z
+date: 2024-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -154,7 +154,10 @@ files:
 - lib/apicraft/web/actions.rb
 - lib/apicraft/web/app.rb
 - lib/apicraft/web/router.rb
-- web/views/index.html
+- web/assets/images/apicraft.png
+- web/assets/images/apicraft_thumb.png
+- web/views/index.erb
+- web/views/rapidoc.erb
 - web/views/redoc.erb
 - web/views/swaggerdoc.erb
 homepage: https://github.com/apicraft-dev/apicraft-rails

data/web/views/index.html

@@ -1,15 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>APICraft</title>
-    <meta charset="utf-8"/>
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
-    <style>
-    </style>
-  </head>
-  <body>
-    <nav>
-    </nav>
-  </body>
-</html>