oas_rails 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dff52d1f5445bbcd000de4c14988e919905c7e5ea1bd179b7ac7c458fde9570e
-  data.tar.gz: adba7ada7bc1658bf3b65f85731eef40c5f72ce930b3b087da5be23b4abd45a8
+  metadata.gz: c9e40d4f8c810e300bbccaf190fd5143e5be804d2d30f1e86393e0478055965f
+  data.tar.gz: 0b6de20a5280115b3550d950da6e26d8424f4d52cc15d6f46f5272224831904e
 SHA512:
-  metadata.gz: 331be1bcbe64381095ab5f62b94154d394340740fe61a43c6463a544c8bc302ae2a89e30b30feedc698673ae4c7eca268b10d59b68e1f607b8eecfdb64917e9b
-  data.tar.gz: edfefc2472d3419045df61ce6ca9a37c48e87d61055b6225af54d7633c8cf08c0471ce15392967c564a866f1e24e322e10defed30ac05736d2b77bd1770fa629
+  metadata.gz: 832e56a728da8974e07d2e83970f6cfd69b892b2e3a89694e08783520ae50698982a59119cf8497d0f2827ca0a4a443a04b80ef03838fe27c596c8dce30a0c1b
+  data.tar.gz: 63d37307fc03dd0d832586ce9e9ae4bdbc1f5480b7624991b7d1aa44323bb1f94c86ccd94a523b31e67b0f3f91fb08cfed00793529294c071192b7079bd4a641

data/README.md

@@ -6,7 +6,7 @@
 
 OasRails is a Rails engine for generating **automatic interactive documentation for your Rails APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
 
-![Screenshot](https://raw.githubusercontent.com/a-chacon/oas_rails/0cfc9abb5be85e6bb3fc4669e29372be8f80a276/oas_rails_ui.png)
+![Screenshot](https://a-chacon.com/assets/images/oas_rails_ui.png)
 
 ## Related Projects
 
@@ -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/configuration.rb

@@ -34,6 +34,14 @@ module OasRails
     def tags=(value)
       @tags = value.map { |t| Tag.new(name: t[:name], description: t[:description]) }
     end
+
+    def excluded_columns_incoming
+      %i[id created_at updated_at deleted_at]
+    end
+
+    def excluded_columns_outgoing
+      []
+    end
   end
 
   DEFAULT_SECURITY_SCHEMES = {

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/esquema_builder.rb

@@ -0,0 +1,37 @@
+module OasRails
+  module EsquemaBuilder
+    class << self
+      # Builds a schema for a class when it is used as incoming API data.
+      #
+      # @param klass [Class] The class for which the schema is built.
+      # @return [Hash] The schema as a JSON-compatible hash.
+      def build_incoming_schema(klass:)
+        configure_common_settings
+        Esquema.configuration.excluded_columns = OasRails.config.excluded_columns_incoming
+
+        Esquema::Builder.new(klass).build_schema.as_json
+      end
+
+      # Builds a schema for a class when it is used as outgoing API data.
+      #
+      # @param klass [Class] The class for which the schema is built.
+      # @return [Hash] The schema as a JSON-compatible hash.
+      def build_outgoing_schema(klass:)
+        configure_common_settings
+        Esquema.configuration.excluded_columns = OasRails.config.excluded_columns_outgoing
+
+        Esquema::Builder.new(klass).build_schema.as_json
+      end
+
+      private
+
+      # Configures common settings for schema building.
+      #
+      # Excludes associations and foreign keys from the schema.
+      def configure_common_settings
+        Esquema.configuration.exclude_associations = true
+        Esquema.configuration.exclude_foreign_keys = true
+      end
+    end
+  end
+end

data/lib/oas_rails/extractors/render_response_extractor.rb

@@ -0,0 +1,173 @@
+module OasRails
+  module Extractors
+    # Extracts and processes render responses from a given source.
+    module RenderResponseExtractor
+      class << self
+        # Extracts responses from the provided source string.
+        #
+        # @param source [String] The source string containing render calls.
+        # @return [Array<Response>] An array of Response objects extracted from the source.
+        def extract_responses_from_source(source:)
+          render_calls = extract_render_calls(source)
+
+          return [Response.new(code: 204, description: "No Content", content: {})] if render_calls.empty?
+
+          render_calls.map { |render_content, status| process_render_content(render_content.strip, status) }
+        end
+
+        private
+
+        # Extracts render calls from the source string.
+        #
+        # @param source [String] The source string containing render calls.
+        # @return [Array<Array<String, String>>] An array of arrays, each containing render content and status.
+        def extract_render_calls(source)
+          source.scan(/render json: ((?:\{.*?\}|\S+))(?:, status: :(\w+))?(?:,.*?)?$/m)
+        end
+
+        # Processes the render content and status to build a Response object.
+        #
+        # @param content [String] The content extracted from the render call.
+        # @param status [String] The status code associated with the render call.
+        # @return [Response] A Response object based on the processed content and status.
+        def process_render_content(content, status)
+          schema, examples = build_schema_and_examples(content)
+          status_int = status_to_integer(status)
+          Response.new(
+            code: status_int,
+            description: status_code_to_text(status_int),
+            content: { "application/json": MediaType.new(schema:, examples:) }
+          )
+        end
+
+        # Builds schema and examples based on the content type.
+        #
+        # @param content [String] The content extracted from the render call.
+        # @return [Array<Hash, Hash>] An array where the first element is the schema and the second is the examples.
+        def build_schema_and_examples(content)
+          if content.start_with?('{')
+            [Utils.hash_to_json_schema(parse_hash_structure(content)), {}]
+          else
+            process_non_hash_content(content)
+          end
+        rescue StandardError => e
+          Rails.logger.debug("Error building schema: #{e.message}")
+          [{}]
+        end
+
+        # Processes non-hash content (e.g., model or method calls) to build schema and examples.
+        #
+        # @param content [String] The content extracted from the render call.
+        # @return [Array<Hash, Hash>] An array where the first element is the schema and the second is the examples.
+        def process_non_hash_content(content)
+          maybe_a_model, errors = content.gsub('@', "").split(".")
+          klass = maybe_a_model.singularize.camelize(:upper).constantize
+
+          if klass.ancestors.include?(ActiveRecord::Base)
+            schema = EsquemaBuilder.build_outgoing_schema(klass:)
+            if test_singularity(maybe_a_model)
+              build_singular_model_schema_and_examples(maybe_a_model, errors, klass, schema)
+            else
+              build_array_model_schema_and_examples(maybe_a_model, klass, schema)
+            end
+          else
+            [{}]
+          end
+        end
+
+        # Builds schema and examples for singular models.
+        #
+        # @param maybe_a_model [String] The model name or variable.
+        # @param errors [String, nil] Errors related to the model.
+        # @param klass [Class] The class associated with the model.
+        # @param schema [Hash] The schema for the model.
+        # @return [Array<Hash, Hash>] An array where the first element is the schema and the second is the examples.
+        def build_singular_model_schema_and_examples(_maybe_a_model, errors, klass, schema)
+          if errors.nil?
+            [schema, MediaType.search_for_examples_in_tests(klass:, context: :outgoing)]
+          else
+            [
+              {
+                type: "object",
+                properties: {
+                  success: { type: "boolean" },
+                  errors: {
+                    type: "object",
+                    additionalProperties: {
+                      type: "array",
+                      items: { type: "string" }
+                    }
+                  }
+                }
+              },
+              {}
+            ]
+          end
+        end
+
+        # Builds schema and examples for array models.
+        #
+        # @param maybe_a_model [String] The model name or variable.
+        # @param klass [Class] The class associated with the model.
+        # @param schema [Hash] The schema for the model.
+        # @return [Array<Hash, Hash>] An array where the first element is the schema and the second is the examples.
+        def build_array_model_schema_and_examples(maybe_a_model, klass, schema)
+          examples = { maybe_a_model => { value: MediaType.search_for_examples_in_tests(klass:, context: :outgoing).values.map { |p| p.dig(:value, maybe_a_model.singularize.to_sym) } } }
+          [{ type: "array", items: schema }, examples]
+        end
+
+        # Determines if a string represents a singular model.
+        #
+        # @param str [String] The string to test.
+        # @return [Boolean] True if the string is a singular model, false otherwise.
+        def test_singularity(str)
+          str.pluralize != str && str.singularize == str
+        end
+
+        # Parses a hash literal to determine its structure.
+        #
+        # @param hash_literal [String] The hash literal string.
+        # @return [Hash<Symbol, String>] A hash representing the structure of the input.
+        def parse_hash_structure(hash_literal)
+          structure = {}
+
+          hash_literal.scan(/(\w+):\s*(\S+)/) do |key, value|
+            structure[key.to_sym] = case value
+                                    when 'true', 'false'
+                                      'Boolean'
+                                    when /^\d+$/
+                                      'Number'
+                                    else
+                                      'Object'
+                                    end
+          end
+
+          structure
+        end
+
+        # Converts a status symbol or string to an integer.
+        #
+        # @param status [String, Symbol, nil] The status to convert.
+        # @return [Integer] The status code as an integer.
+        def status_to_integer(status)
+          return 200 if status.nil?
+
+          if status.to_s =~ /^\d+$/
+            status.to_i
+          else
+            status = "unprocessable_content" if status == "unprocessable_entity"
+            Rack::Utils::SYMBOL_TO_STATUS_CODE[status.to_sym]
+          end
+        end
+
+        # Converts a status code to its corresponding text description.
+        #
+        # @param status_code [Integer] The status code.
+        # @return [String] The text description of the status code.
+        def status_code_to_text(status_code)
+          Rack::Utils::HTTP_STATUS_CODES[status_code] || "Unknown Status Code"
+        end
+      end
+    end
+  end
+end

data/lib/oas_rails/extractors/route_extractor.rb

@@ -0,0 +1,125 @@
+module OasRails
+  module Extractors
+    class RouteExtractor
+      RAILS_DEFAULT_CONTROLLERS = %w[
+        rails/info
+        rails/mailers
+        active_storage/blobs
+        active_storage/disk
+        active_storage/direct_uploads
+        active_storage/representations
+        rails/conductor/continuous_integration
+        rails/conductor/multiple_databases
+        rails/conductor/action_mailbox
+        rails/conductor/action_text
+        action_cable
+      ].freeze
+
+      RAILS_DEFAULT_PATHS = %w[
+        /rails/action_mailbox/
+      ].freeze
+
+      class << self
+        def host_routes_by_path(path)
+          @host_routes ||= extract_host_routes
+          @host_routes.select { |r| r.path == path }
+        end
+
+        def host_routes
+          @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
+
+        def clean_route(route)
+          route.gsub('(.:format)', '').gsub(/:\w+/) { |match| "{#{match[1..]}}" }
+        end
+
+        # THIS CODE IS NOT IN USE BUT CAN BE USEFULL WITH GLOBAL TAGS OR AUTH TAGS
+        # def get_controller_comments(controller_path)
+        #   YARD.parse_string(File.read(controller_path))
+        #   controller_class = YARD::Registry.all(:class).first
+        #   if controller_class
+        #     class_comment = controller_class.docstring.all
+        #     method_comments = controller_class.meths.map do |method|
+        #       {
+        #         name: method.name,
+        #         comment: method.docstring.all
+        #       }
+        #     end
+        #     YARD::Registry.clear
+        #     {
+        #       class_comment: class_comment,
+        #       method_comments: method_comments
+        #     }
+        #   else
+        #     YARD::Registry.clear
+        #     nil
+        #   end
+        # rescue StandardError
+        #   nil
+        # end
+        #
+        # def get_controller_comment(controller_path)
+        #   get_controller_comments(controller_path)&.dig(:class_comment) || ''
+        # rescue StandardError
+        #   ''
+        # end
+
+        private
+
+        def extract_host_routes
+          valid_routes.map { |r| OasRoute.new_from_rails_route(rails_route: r) }
+        end
+
+        def valid_routes
+          Rails.application.routes.routes.select do |route|
+            valid_api_route?(route)
+          end
+        end
+
+        def valid_api_route?(route)
+          return false unless valid_route_implementation?(route)
+          return false if RAILS_DEFAULT_CONTROLLERS.any? { |default| route.defaults[:controller].start_with?(default) }
+          return false if RAILS_DEFAULT_PATHS.any? { |path| route.path.spec.to_s.include?(path) }
+          return false unless route.path.spec.to_s.start_with?(OasRails.config.api_path)
+
+          true
+        end
+
+        # Checks if a route has a valid implementation.
+        #
+        # This method verifies that both the controller and the action specified
+        # in the route exist. It checks if the controller class is defined and
+        # if the action method is implemented within that controller.
+        #
+        # @param route [ActionDispatch::Journey::Route] The route to check.
+        # @return [Boolean] true if both the controller and action exist, false otherwise.
+        def valid_route_implementation?(route)
+          controller_name = route.defaults[:controller]&.camelize
+          action_name = route.defaults[:action]
+
+          return false if controller_name.blank? || action_name.blank?
+
+          controller_class = "#{controller_name}Controller".safe_constantize
+
+          if controller_class.nil?
+            false
+          else
+            controller_class.instance_methods.include?(action_name.to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/oas_rails/media_type.rb

@@ -2,18 +2,29 @@ module OasRails
   class MediaType < OasBase
     attr_accessor :schema, :example, :examples, :encoding
 
+    # Initializes a new MediaType object.
+    #
+    # @param schema [Hash] the schema of the media type.
+    # @param kwargs [Hash] additional keyword arguments.
     def initialize(schema:, **kwargs)
       super()
       @schema = schema
       @example = kwargs[:example] || {}
-      @examples = kwargs[:examples] || []
+      @examples = kwargs[:examples] || {}
     end
 
     class << self
-      def from_model_class(klass:, examples: {})
+      @context = :incoming
+      # Creates a new MediaType object from a model class.
+      #
+      # @param klass [Class] the ActiveRecord model class.
+      # @param examples [Hash] the examples hash.
+      # @return [MediaType, nil] the created MediaType object or nil if the class is not an ActiveRecord model.
+      def from_model_class(klass:, context: :incoming, examples: {})
+        @context = context
         return unless klass.ancestors.include? ActiveRecord::Base
 
-        model_schema = Esquema::Builder.new(klass).build_schema.as_json
+        model_schema = EsquemaBuilder.send("build_#{@context}_schema", klass:)
         model_schema["required"] = []
         schema = { type: "object", properties: { klass.to_s.downcase => model_schema } }
         examples.merge!(search_for_examples_in_tests(klass:))
@@ -22,45 +33,25 @@ module OasRails
 
       # 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)
+      def search_for_examples_in_tests(klass:, context: :incoming, utils: Utils)
+        @context = context
         case utils.detect_test_framework
         when :factory_bot
-          {}
-          # TODO: create examples with FactoryBot
+          fetch_factory_bot_examples(klass:)
         when :fixtures
-          fixture_file = Rails.root.join('test', 'fixtures', "#{klass.to_s.pluralize.downcase}.yml")
-
-          begin
-            fixture_data = YAML.load_file(fixture_file).with_indifferent_access
-          rescue Errno::ENOENT
-            return {}
-          end
-
-          fixture_data.transform_values { |attributes| { value: { klass.to_s.downcase => attributes } } }
+          fetch_fixture_examples(klass:)
         else
           {}
         end
       end
 
+      # Transforms tags into examples.
+      #
+      # @param tags [Array] the array of tags.
+      # @return [Hash] the transformed examples hash.
       def tags_to_examples(tags:)
         tags.each_with_object({}).with_index(1) do |(example, result), _index|
           key = example.text.downcase.gsub(' ', '_')
@@ -71,6 +62,41 @@ module OasRails
           result[key] = value
         end
       end
+
+      private
+
+      # Fetches examples from FactoryBot for the provided class.
+      #
+      # @param klass [Class] the class to fetch examples for.
+      # @return [Hash] a hash containing examples data or an empty hash if no examples are found.
+      def fetch_factory_bot_examples(klass:)
+        klass_sym = klass.to_s.downcase.to_sym
+        begin
+          FactoryBot.build_stubbed_list(klass_sym, 3).each_with_index.to_h do |obj, index|
+            ["#{klass_sym}#{index + 1}", { value: { klass_sym => clean_example_object(obj: obj.as_json) } }]
+          end
+        rescue KeyError
+          {}
+        end
+      end
+
+      # Fetches examples from fixtures for the provided class.
+      #
+      # @param klass [Class] the class to fetch examples for.
+      # @return [Hash] a hash containing examples data or an empty hash if no examples are found.
+      def fetch_fixture_examples(klass:)
+        fixture_file = Rails.root.join('test', 'fixtures', "#{klass.to_s.pluralize.downcase}.yml")
+        begin
+          fixture_data = YAML.load_file(fixture_file).with_indifferent_access
+        rescue Errno::ENOENT
+          return {}
+        end
+        fixture_data.transform_values { |attributes| { value: { klass.to_s.downcase => clean_example_object(obj: attributes) } } }
+      end
+
+      def clean_example_object(obj:)
+        obj.reject { |key, _| OasRails.config.send("excluded_columns_#{@context}").include?(key.to_sym) }
+      end
     end
   end
 end

data/lib/oas_rails/oas_route.rb

@@ -19,13 +19,13 @@ module OasRails
       @controller_path = controller_path_extractor(@rails_route.defaults[:controller])
       @method = @rails_route.defaults[:action]
       @verb = @rails_route.verb
-      @path = RouteExtractor.clean_route(@rails_route.path.spec.to_s)
+      @path = Extractors::RouteExtractor.clean_route(@rails_route.path.spec.to_s)
       @docstring = extract_docstring
       @source_string = extract_source_string
     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
@@ -46,98 +46,5 @@ module OasRails
       klass = @controller.singularize.camelize.constantize
       RequestBody.from_model_class(klass:, required: true)
     end
-
-    def extract_responses_from_source
-      render_calls = @source_string.scan(/render json: ((?:\{.*?\}|\S+))(?:, status: :(\w+))?(?:,.*?)?$/m)
-
-      return [Response.new(code: 204, description: "No Content", content: {})] if render_calls.empty?
-
-      render_calls.map do |render_content, status|
-        content = render_content.strip
-
-        # TODO: manage when is an array of errors
-        schema = {}
-        begin
-          schema = if content.start_with?('{')
-                     Utils.hash_to_json_schema(parse_hash_structure(content))
-                   else
-                     # It's likely a variable or method call
-                     maybe_a_model, errors = content.gsub('@', "").split(".")
-                     klass = maybe_a_model.singularize.camelize(:upper).constantize
-                     return {} unless klass.ancestors.include? ActiveRecord::Base
-
-                     e = Esquema::Builder.new(klass).build_schema.as_json
-                     if test_singularity(maybe_a_model)
-                       if errors.nil?
-                         e
-                       else
-                         {
-                           type: "object",
-                           properties: {
-                             success: {
-                               type: "boolean"
-                             },
-                             errors: {
-                               type: "object",
-                               additionalProperties: {
-                                 type: "array",
-                                 items: {
-                                   type: "string"
-                                 }
-                               }
-                             }
-                           }
-                         } end
-                     else
-                       { type: "array", items: e }
-                     end
-                   end
-        rescue StandardError => e
-          Rails.logger.debug("Error building schema: #{e.message}")
-        end
-
-        status_int = status_to_integer(status)
-        Response.new(code: status_int, description: status_code_to_text(status_int), content: { "application/json": MediaType.new(schema:) })
-      end
-    end
-
-    def test_singularity(str)
-      str.pluralize != str && str.singularize == str
-    end
-
-    def parse_hash_structure(hash_literal)
-      structure = {}
-
-      hash_literal.scan(/(\w+):\s*(\S+)/) do |key, value|
-        structure[key.to_sym] = case value
-                                when 'true', 'false'
-                                  'Boolean'
-                                when /^\d+$/
-                                  'Number'
-                                when '@user.errors'
-                                  'Object'
-                                else
-                                  'Object'
-                                end
-      end
-
-      structure
-    end
-
-    def status_to_integer(status)
-      return 200 if status.nil?
-
-      if status.to_s =~ /^\d+$/
-        status.to_i
-      else
-        status = "unprocessable_content" if status == "unprocessable_entity"
-        Rack::Utils::SYMBOL_TO_STATUS_CODE[status.to_sym]
-
-      end
-    end
-
-    def status_code_to_text(status_code)
-      Rack::Utils::HTTP_STATUS_CODES[status_code] || "Unknown Status Code"
-    end
   end
 end

data/lib/oas_rails/operation.rb

@@ -104,7 +104,7 @@ module OasRails
         responses = Responses.from_tags(tags: oas_route.docstring.tags(:response))
 
         if OasRails.config.autodiscover_responses
-          new_responses = oas_route.extract_responses_from_source
+          new_responses = Extractors::RenderResponseExtractor.extract_responses_from_source(source: oas_route.source_string)
 
           new_responses.each do |new_response|
             responses.responses << new_response unless responses.responses.any? { |r| r.code == new_response.code }

data/lib/oas_rails/paths.rb

@@ -8,7 +8,7 @@ module OasRails
 
     def self.from_string_paths(string_paths:)
       new(path_items: string_paths.map do |s|
-                        PathItem.from_oas_routes(path: s, oas_routes: RouteExtractor.host_routes_by_path(s))
+                        PathItem.from_oas_routes(path: s, oas_routes: Extractors::RouteExtractor.host_routes_by_path(s))
                       end)
     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
+      Extractors::RouteExtractor.clear_cache
+    end
+
     def to_json(*_args)
       @specification.to_json
     rescue StandardError => e
@@ -41,7 +51,7 @@ module OasRails
     # Create the Paths Object For the Root of the OAS.
     # @see https://spec.openapis.org/oas/latest.html#paths-object
     def paths
-      Paths.from_string_paths(string_paths: RouteExtractor.host_paths).to_spec
+      Paths.from_string_paths(string_paths: Extractors::RouteExtractor.host_paths).to_spec
     end
 
     # Created the Components Object For the Root of the OAS.

data/lib/oas_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 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

@@ -9,7 +9,6 @@ module OasRails
   autoload :OasBase, "oas_rails/oas_base"
   autoload :Configuration, "oas_rails/configuration"
   autoload :Specification, "oas_rails/specification"
-  autoload :RouteExtractor, "oas_rails/route_extractor"
   autoload :OasRoute, "oas_rails/oas_route"
   autoload :Operation, "oas_rails/operation"
   autoload :Info, "oas_rails/info"
@@ -26,13 +25,21 @@ module OasRails
   autoload :Responses, "oas_rails/responses"
 
   autoload :Utils, "oas_rails/utils"
+  autoload :EsquemaBuilder, "oas_rails/esquema_builder"
 
-  module Yard
-    autoload :OasYardFactory, 'oas_rails/yard/oas_yard_factory'
+  module YARD
+    autoload :OasYARDFactory, 'oas_rails/yard/oas_yard_factory'
+  end
+
+  module Extractors
+    autoload :RenderResponseExtractor, 'oas_rails/extractors/render_response_extractor'
+    autoload :RouteExtractor, "oas_rails/extractors/route_extractor"
   end
 
   class << self
+    # Configurations for make the OasRails engine Work.
     def configure
+      OasRails.configure_yard!
       yield config
     end
 
@@ -41,7 +48,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],
@@ -56,13 +63,5 @@ module OasRails
         ::YARD::Tags::Library.define_tag(tag_name, method_name, handler)
       end
     end
-
-    def configure_esquema!
-      Esquema.configure do |config|
-        config.exclude_associations = true
-        config.exclude_foreign_keys = true
-        config.excluded_columns = %i[id created_at updated_at deleted_at]
-      end
-    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oas_rails
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - a-chacon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-07-31 00:00:00.000000000 Z
+date: 2024-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: esquema
@@ -103,6 +103,9 @@ files:
 - lib/oas_rails/configuration.rb
 - lib/oas_rails/contact.rb
 - lib/oas_rails/engine.rb
+- lib/oas_rails/esquema_builder.rb
+- lib/oas_rails/extractors/render_response_extractor.rb
+- lib/oas_rails/extractors/route_extractor.rb
 - lib/oas_rails/info.rb
 - lib/oas_rails/license.rb
 - lib/oas_rails/media_type.rb
@@ -115,7 +118,6 @@ files:
 - lib/oas_rails/request_body.rb
 - lib/oas_rails/response.rb
 - lib/oas_rails/responses.rb
-- lib/oas_rails/route_extractor.rb
 - lib/oas_rails/server.rb
 - lib/oas_rails/specification.rb
 - lib/oas_rails/tag.rb

data/lib/oas_rails/route_extractor.rb

@@ -1,111 +0,0 @@
-module OasRails
-  class RouteExtractor
-    RAILS_DEFAULT_CONTROLLERS = %w[
-      rails/info
-      rails/mailers
-      active_storage/blobs
-      active_storage/disk
-      active_storage/direct_uploads
-      active_storage/representations
-      rails/conductor/continuous_integration
-      rails/conductor/multiple_databases
-      rails/conductor/action_mailbox
-      rails/conductor/action_text
-      action_cable
-    ].freeze
-
-    RAILS_DEFAULT_PATHS = %w[
-      /rails/action_mailbox/
-    ].freeze
-
-    class << self
-      def host_routes_by_path(path)
-        @host_routes ||= extract_host_routes
-        @host_routes.select { |r| r.path == path }
-      end
-
-      def host_routes
-        @host_routes ||= extract_host_routes
-      end
-
-      def host_paths
-        @host_paths ||= host_routes.map(&:path).uniq.sort
-      end
-
-      def clean_route(route)
-        route.gsub('(.:format)', '').gsub(/:\w+/) { |match| "{#{match[1..]}}" }
-      end
-
-      # THIS CODE IS NOT IN USE BUT CAN BE USEFULL WITH GLOBAL TAGS OR AUTH TAGS
-      # def get_controller_comments(controller_path)
-      #   YARD.parse_string(File.read(controller_path))
-      #   controller_class = YARD::Registry.all(:class).first
-      #   if controller_class
-      #     class_comment = controller_class.docstring.all
-      #     method_comments = controller_class.meths.map do |method|
-      #       {
-      #         name: method.name,
-      #         comment: method.docstring.all
-      #       }
-      #     end
-      #     YARD::Registry.clear
-      #     {
-      #       class_comment: class_comment,
-      #       method_comments: method_comments
-      #     }
-      #   else
-      #     YARD::Registry.clear
-      #     nil
-      #   end
-      # rescue StandardError
-      #   nil
-      # end
-      #
-      # def get_controller_comment(controller_path)
-      #   get_controller_comments(controller_path)&.dig(:class_comment) || ''
-      # rescue StandardError
-      #   ''
-      # end
-
-      private
-
-      def extract_host_routes
-        Rails.application.routes.routes.select do |route|
-          valid_api_route?(route)
-        end.map { |r| OasRoute.new_from_rails_route(rails_route: r) }
-      end
-
-      def valid_api_route?(route)
-        return false unless valid_route_implementation?(route)
-        return false if RAILS_DEFAULT_CONTROLLERS.any? { |default| route.defaults[:controller].start_with?(default) }
-        return false if RAILS_DEFAULT_PATHS.any? { |path| route.path.spec.to_s.include?(path) }
-        return false unless route.path.spec.to_s.start_with?(OasRails.config.api_path)
-
-        true
-      end
-
-      # Checks if a route has a valid implementation.
-      #
-      # This method verifies that both the controller and the action specified
-      # in the route exist. It checks if the controller class is defined and
-      # if the action method is implemented within that controller.
-      #
-      # @param route [ActionDispatch::Journey::Route] The route to check.
-      # @return [Boolean] true if both the controller and action exist, false otherwise.
-      def valid_route_implementation?(route)
-        controller_name = route.defaults[:controller]&.camelize
-        action_name = route.defaults[:action]
-
-        return false if controller_name.blank? || action_name.blank?
-
-        controller_class = "#{controller_name}Controller".safe_constantize
-
-        if controller_class.nil?
-          false
-        else
-          controller_class.instance_methods.include?(action_name.to_sym)
-        end
-      end
-    end
-  end
-end