oas_rails 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2424eec4c6a122256970ba124f71c0f5dfd9b4392875ac678d4868883cc233ae
-  data.tar.gz: 182e2434b480920d8cabdd0899c96d48f6c7a69abe5432c33e27f4bc845f3a0c
+  metadata.gz: 4c6823d6b64ffb6edbeabed87d2985f006433d6c8243d6e42bf21a6c96fab1e1
+  data.tar.gz: 85e8a04aa51388ce0ba2f0e27da7c81176ecc1e62630e301147ac0d1bd57fbac
 SHA512:
-  metadata.gz: f0437d44b6b053a3e95659ed43957d3455826ba2981f02140c23f323c5997434aa3c1adbe232188da55b6f62e3ff67e3c83a4a58d64973023555448f14ae964f
-  data.tar.gz: 5f2edc1bc10dab27b4ff13c9a583bf73c3855dd65c06055dfd26b63d89034d607d5794cf331356b8759443b1a0e072cc0a96fbbc6260ea83641826c0ca66f96c
+  metadata.gz: cfd37bb135fcbe966a2ad9972f5339f9c3c196cc10234a65570e023d8ae4386f4d55bac813f51c3da6cb5f4d2f29c49c8294f29eb391d405fa437fe5c5b34375
+  data.tar.gz: 49e84dddf1baeb860ae753757a72c5a9989e4c1fd49dcc9b9beb79ea52323a330eb054236e3329756192e68fd43c2cc1ec9f0ea6f269082c0191d4ca184b5596

data/README.md

@@ -30,6 +30,24 @@ After experiencing the interactive documentation in Python's fast-api framework,
 
 The goal is to minimize the effort required to create comprehensive documentation. By following REST principles in Rails, we believe this is achievable. You can enhance the documentation using [Yard](https://yardoc.org/) tags.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Basic Information about the API](#basic-information-about-the-api)
+  - [Servers Information](#servers-information)
+  - [Tag Information](#tag-information)
+  - [Optional Settings](#optional-settings)
+  - [Authentication Settings](#authentication-settings)
+- [Usage](#usage)
+  - [Documenting Your Endpoints](#documenting-your-endpoints)
+  - [Example](#example-of-documented-endpoints)
+- [Securing the OasRails Engine](#securing-the-oasrails-engine)
+- [Customizing the View](#customizing-the-view)
+- [Contributing](#contributing)
+  - [Roadmap and Ideas for Improvement](#roadmap-and-ideas-for-improvement)
+- [License](#license)
+
 ## Installation
 
 1. Add this line to your Rails application's Gemfile:
@@ -52,23 +70,15 @@ The goal is to minimize the effort required to create comprehensive documentatio
 
 You'll now have **basic documentation** based on your routes and automatically gathered information at `localhost:3000/docs`. To enhance it, create an initializer file and add [Yard](https://yardoc.org/) tags to your controller methods.
 
-## Usage
-
-### Initializer File
+## Configuration
 
-You can easy create the initializer file with:
+To configure OasRails, you MUST create an initializer file including all your settings. The first step is to create your initializer file, which you can easily do with:
 
 ```bash
 rails generate oas_rails:config
 ```
 
-Then complete the created file with your data.
-
-**Almost every description in a OAS file support simple markdown**
-
-## Configuration
-
-To configure OasRails, edit the `config/initializers/oas_rails.rb` file. Below are the available configuration options:
+Then fill it with your data. Below are the available configuration options:
 
 ### Basic Information about the API
 
@@ -100,56 +110,11 @@ To configure OasRails, edit the `config/initializers/oas_rails.rb` file. Below a
 - `config.security_schema`: The default security schema used for authentication. Choose a predefined security schema from `[:api_key_cookie, :api_key_header, :api_key_query, :basic, :bearer, :bearer_jwt, :mutual_tls]`.
 - `config.security_schemas`: Custom security schemas. Follow the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html#security-scheme-object) for defining these schemas.
 
-## Securing the OasRails Engine
-
-To secure the OasRails engine, which exposes an endpoint for showing the OAS definition, you can configure authentication to ensure that only authorized users have access. Here are a few methods to achieve this:
-
-### 1. Using Basic Authentication
-
-Use basic authentication to protect the OasRails endpoint. You can set this up in an initializer:
-
-```ruby
-# config/initializers/oas_rails.rb
-OasRails::Engine.middleware.use(Rack::Auth::Basic) do |username, password|
-  ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.oas_rails_username, username) &
-    ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.oas_rails_password, password)
-end
-```
-
-### 2. Using Devise's `authenticate` Helper
-
-You can use Devise's `authenticate` helper to restrict access to the OasRails endpoint. For example, you can allow only admin users to access the endpoint:
-
-```ruby
-# config/routes.rb
-# ...
-authenticate :user, ->(user) { user.admin? } do
-  mount OasRails::Engine, at: '/docs'
-end
-```
-
-### 3. Custom Authentication
-
-To support custom authentication, you can extend the OasRails' ApplicationController using a hook. This allows you to add custom before actions to check for specific user permissions:
-
-```ruby
-# config/initializers/oas_rails.rb
-
-ActiveSupport.on_load(:oas_rails_application_controller) do
-  # context here is OasRails::ApplicationController
-
-  before_action do
-    raise ActionController::RoutingError.new('Not Found') unless current_user&.admin?
-  end
+## Usage
 
-  def current_user
-    # Load the current user
-    User.find(session[:user_id]) # Adjust according to your authentication logic
-  end
-end
-```
+In addition to the information provided in the initializer file and the data that can be extracted from the routes and methods automatically, it is essential to document your API in the following way. The documentation is created **with the help of YARD**, so the methods are documented with **comment tags**.
 
-## Documenting Your Endpoints
+### Documenting Your Endpoints
 
 Almost every description in an OAS file supports simple markdown. The following tags are available for documenting your endpoints:
 
@@ -331,9 +296,74 @@ class UsersController < ApplicationController
 end
 ```
 
+## Securing the OasRails Engine
+
+To secure the OasRails engine, which exposes an endpoint for showing the OAS definition, you can configure authentication to ensure that only authorized users have access. Here are a few methods to achieve this:
+
+### 1. Using Basic Authentication
+
+Use basic authentication to protect the OasRails endpoint. You can set this up in an initializer:
+
+```ruby
+# config/initializers/oas_rails.rb
+OasRails::Engine.middleware.use(Rack::Auth::Basic) do |username, password|
+  ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.oas_rails_username, username) &
+    ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.oas_rails_password, password)
+end
+```
+
+### 2. Using Devise's `authenticate` Helper
+
+You can use Devise's `authenticate` helper to restrict access to the OasRails endpoint. For example, you can allow only admin users to access the endpoint:
+
+```ruby
+# config/routes.rb
+# ...
+authenticate :user, ->(user) { user.admin? } do
+  mount OasRails::Engine, at: '/docs'
+end
+```
+
+### 3. Custom Authentication
+
+To support custom authentication, you can extend the OasRails' ApplicationController using a hook. This allows you to add custom before actions to check for specific user permissions:
+
+```ruby
+# config/initializers/oas_rails.rb
+
+ActiveSupport.on_load(:oas_rails_application_controller) do
+  # context here is OasRails::ApplicationController
+
+  before_action do
+    raise ActionController::RoutingError.new('Not Found') unless current_user&.admin?
+  end
+
+  def current_user
+    # Load the current user
+    User.find(session[:user_id]) # Adjust according to your authentication logic
+  end
+end
+```
+
+## Customizing the View
+
+The OasRails engine provides an easy way to display your OpenAPI Specification (OAS) within your Rails application. By default, it includes an `index` view in the `OasRailsController` that displays [RapiDoc](https://rapidocweb.com/) through a CDN with default configurations. You can easily override this view to replace RapiDoc entirely or configure it differently.
+
+#### Overriding the `index` View
+
+To override the `index` view provided by the OasRails engine, follow these steps:
+
+1. **Create the Override View File**: In your host application, create a new file at the path `app/views/oas_rails/oas_rails/index.html.erb`. If the directories do not exist, you will need to create them.
+
+2. **Customize the View**: Open the newly created `index.html.erb` file and add your custom HTML and ERB code to display the OAS as desired. You can refer to the source code of this project for guidance.
+
+#### Using the Custom View
+
+Once the custom view file is in place, Rails will automatically use it instead of the view provided by the OasRails engine. This allows you to fully customize the presentation of the OAS without modifying the engine's code.
+
 ## Contributing
 
-Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star⭐! Thanks again!
 
 1. Fork the Project
 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)

data/app/controllers/oas_rails/oas_rails_controller.rb

@@ -1,5 +1,7 @@
 module OasRails
   class OasRailsController < ApplicationController
+    layout false
+
     def index
       respond_to do |format|
         format.html

data/app/views/layouts/oas_rails/application.html.erb

@@ -1,16 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>Oas rails</title>
-    <%= csrf_meta_tags %>
-    <%= csp_meta_tag %>
-    <meta charset="utf-8">
-    <!-- Important: rapi-doc uses utf8 characters -->
-    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
-  </head>
-  <body>
-
-    <%= yield %>
-
-  </body>
-</html>

data/app/views/oas_rails/oas_rails/index.html.erb

@@ -1 +1,27 @@
-<rapi-doc spec-url = "<%= main_app.oas_rails_path %>.json" theme = "dark" text-color="#f9f9f9" show-header = 'false'> </rapi-doc>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Oas rails</title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <meta charset="utf-8">
+    <!-- Important: rapi-doc uses utf8 characters -->
+    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+  </head>
+  <body>
+    <rapi-doc 
+      spec-url = "<%= main_app.oas_rails_path %>.json" 
+      theme = "dark" 
+      bg-color="#0F172A"
+      text-color= "#f7f7f7" 
+      show-header = 'false'
+      primary-color = "#2de410"
+      font-size="largest"
+      show-method-in-nav-bar="as-colored-text"
+      nav-text-color="#f7f7f7"
+      nav-item-spacing="relaxed"
+      allow-spec-file-download="true"
+      > 
+    </rapi-doc>
+  </body>
+</html>

data/lib/oas_rails/engine.rb

@@ -1,5 +1,10 @@
 module OasRails
   class Engine < ::Rails::Engine
     isolate_namespace OasRails
+    config.to_prepare do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym 'YARD'
+      end
+    end
   end
 end

data/lib/oas_rails/media_type.rb

@@ -20,23 +20,42 @@ module OasRails
         new(media_type: "", schema:, examples:)
       end
 
-      def search_for_examples_in_tests(klass:)
-        case Utils.detect_test_framework
+      # Searches for examples in test files based on the provided class and test framework.
+      #
+      # This method handles different test frameworks to fetch examples for the given class.
+      # Currently, it supports FactoryBot and fixtures.
+      #
+      # @param klass [Class] the class to search examples for.
+      # @param utils [Module] a utility module that provides the `detect_test_framework` method. Defaults to `Utils`.
+      # @return [Hash] a hash containing examples data or an empty hash if no examples are found.
+      # @example Usage with FactoryBot
+      #   search_for_examples_in_tests(klass: User)
+      #
+      # @example Usage with fixtures
+      #   search_for_examples_in_tests(klass: Project)
+      #
+      # @example Usage with a custom utils module
+      #   custom_utils = Module.new do
+      #     def self.detect_test_framework
+      #       :factory_bot
+      #     end
+      #   end
+      #   search_for_examples_in_tests(klass: User, utils: custom_utils)
+      def search_for_examples_in_tests(klass:, utils: Utils)
+        case utils.detect_test_framework
         when :factory_bot
           {}
           # TODO: create examples with FactoryBot
         when :fixtures
-          # Handle fixtures scenario
           fixture_file = Rails.root.join('test', 'fixtures', "#{klass.to_s.pluralize.downcase}.yml")
-          fixture_data = YAML.load_file(fixture_file).with_indifferent_access
 
-          users_hash = {}
-
-          # Convert the fixture data to a hash
-          fixture_data.each do |name, attributes|
-            users_hash[name] = { value: { klass.to_s.downcase => attributes } }
+          begin
+            fixture_data = YAML.load_file(fixture_file).with_indifferent_access
+          rescue Errno::ENOENT
+            return {}
           end
-          users_hash
+
+          fixture_data.transform_values { |attributes| { value: { klass.to_s.downcase => attributes } } }
         else
           {}
         end

data/lib/oas_rails/oas_route.rb

@@ -25,7 +25,7 @@ module OasRails
     end
 
     def extract_docstring
-      YARD::Docstring.parser.parse(
+      ::YARD::Docstring.parser.parse(
         controller_class.constantize.instance_method(method).comment.lines.map { |line| line.sub(/^#\s*/, '') }.join
       ).to_docstring
     end

data/lib/oas_rails/route_extractor.rb

@@ -28,6 +28,14 @@ module OasRails
         @host_routes ||= extract_host_routes
       end
 
+      # Clear Class Instance Variable @host_routes
+      #
+      # This method clear the class instance variable @host_routes
+      # to force a extraction of the routes again.
+      def clear_cache
+        @host_routes = nil
+      end
+
       def host_paths
         @host_paths ||= host_routes.map(&:path).uniq.sort
       end

data/lib/oas_rails/specification.rb

@@ -2,12 +2,22 @@ require 'json'
 
 module OasRails
   class Specification
+    # Initializes a new Specification object.
+    # Clears the cache if running in the development environment.
     def initialize
-      OasRails.configure_esquema!
-      OasRails.configure_yard!
+      clear_cache unless Rails.env.production?
+
       @specification = base_spec
     end
 
+    # Clears the cache for MethodSource and RouteExtractor.
+    #
+    # @return [void]
+    def clear_cache
+      MethodSource.clear_cache
+      RouteExtractor.clear_cache
+    end
+
     def to_json(*_args)
       @specification.to_json
     rescue StandardError => e

data/lib/oas_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/lib/oas_rails/yard/oas_yard_factory.rb

@@ -1,5 +1,5 @@
 module OasRails
-  module Yard
+  module YARD
     class RequestBodyTag < ::YARD::Tags::Tag
       attr_accessor :klass, :schema, :required
 
@@ -41,7 +41,7 @@ module OasRails
       end
     end
 
-    class OasYardFactory < ::YARD::Tags::DefaultFactory
+    class OasYARDFactory < ::YARD::Tags::DefaultFactory
       ## parse_tag is a prefix used by YARD
 
       def parse_tag_with_request_body(tag_name, text)

data/lib/oas_rails.rb

@@ -27,12 +27,15 @@ module OasRails
 
   autoload :Utils, "oas_rails/utils"
 
-  module Yard
-    autoload :OasYardFactory, 'oas_rails/yard/oas_yard_factory'
+  module YARD
+    autoload :OasYARDFactory, 'oas_rails/yard/oas_yard_factory'
   end
 
   class << self
+    # Configurations for make the OasRails engine Work.
     def configure
+      OasRails.configure_esquema!
+      OasRails.configure_yard!
       yield config
     end
 
@@ -41,7 +44,7 @@ module OasRails
     end
 
     def configure_yard!
-      ::YARD::Tags::Library.default_factory = Yard::OasYardFactory
+      ::YARD::Tags::Library.default_factory = YARD::OasYARDFactory
       yard_tags = {
         'Request body' => [:request_body, :with_request_body],
         'Request body Example' => [:request_body_example, :with_request_body_example],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oas_rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - a-chacon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-07-31 00:00:00.000000000 Z
+date: 2024-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: esquema