oas_rails 0.2.3 → 0.4.0

data/lib/oas_rails/extractors/render_response_extractor.rb

@@ -0,0 +1,148 @@
+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(specification, source:)
+          render_calls = extract_render_calls(source)
+          return [Builders::ResponseBuilder.new(specification).with_description("No content").with_code(204).build] if render_calls.empty?
+
+          render_calls.map { |render_content, status| process_render_content(specification, 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(specification, content, status)
+          schema, examples = build_schema_and_examples(content)
+          status_int = Utils.status_to_integer(status)
+          content = Builders::ContentBuilder.new(specification, :outgoing).with_schema(schema).with_examples(examples).build
+
+          Builders::ResponseBuilder.new(specification).with_code(status_int).with_description(Utils.status_code_to_text(status_int)).with_content(content).build
+        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, Spec::MediaType.search_for_examples_in_tests(klass, context: :outgoing)]
+          else
+            # TODO: this is not building the real schema.
+            [
+              {
+                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: Spec::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
+      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/oas_route.rb

@@ -19,7 +19,7 @@ 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
@@ -41,103 +41,5 @@ module OasRails
     def controller_path_extractor(controller)
       Rails.root.join("app/controllers/#{controller}_controller.rb").to_s
     end
-
-    def detect_request_body
-      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/spec/components.rb

@@ -0,0 +1,85 @@
+module OasRails
+  module Spec
+    class Components
+      include Specable
+
+      attr_accessor :schemas, :parameters, :security_schemes, :request_bodies, :responses, :headers, :examples, :links, :callbacks
+
+      def initialize(specification)
+        @specification = specification
+        @schemas = {}
+        @parameters = {}
+        @security_schemes = OasRails.config.security_schemas
+        @request_bodies = {}
+        @responses = {}
+        @headers = {}
+        @examples = {}
+        @links = {}
+        @callbacks = {}
+      end
+
+      def oas_fields
+        [:request_bodies, :examples, :responses, :schemas, :parameters, :security_schemes]
+      end
+
+      def add_response(response)
+        key = response.hash_key
+        @responses[key] = response unless @responses.key? key
+
+        response_reference(key)
+      end
+
+      def add_parameter(parameter)
+        key = parameter.hash_key
+        @parameters[key] = parameter unless @parameters.key? key
+
+        parameter_reference(key)
+      end
+
+      def add_request_body(request_body)
+        key = request_body.hash_key
+        @request_bodies[key] = request_body unless @request_bodies.key? key
+
+        request_body_reference(key)
+      end
+
+      def add_schema(schema)
+        key = Hashable.generate_hash(schema)
+        @schemas[key] = schema if @schemas[key].nil?
+
+        schema_reference(key)
+      end
+
+      def add_example(example)
+        key = Hashable.generate_hash(example)
+        @examples[key] = example if @examples[key].nil?
+
+        example_reference(key)
+      end
+
+      def create_reference(type, name)
+        "#/components/#{type}/#{name}"
+      end
+
+      def schema_reference(name)
+        Reference.new(create_reference('schemas', name))
+      end
+
+      def response_reference(name)
+        Reference.new(create_reference('responses', name))
+      end
+
+      def parameter_reference(name)
+        Reference.new(create_reference('parameters', name))
+      end
+
+      def example_reference(name)
+        Reference.new(create_reference('examples', name))
+      end
+
+      def request_body_reference(name)
+        Reference.new(create_reference('requestBodies', name))
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/contact.rb

@@ -0,0 +1,18 @@
+module OasRails
+  module Spec
+    class Contact
+      include Specable
+      attr_accessor :name, :url, :email
+
+      def initialize(**kwargs)
+        @name = kwargs[:name] || ''
+        @url = kwargs[:url] || ''
+        @email = kwargs[:email] || ''
+      end
+
+      def oas_fields
+        [:name, :url, :email]
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/hashable.rb

@@ -0,0 +1,39 @@
+module OasRails
+  module Spec
+    require 'digest'
+
+    module Hashable
+      def hash_key
+        Hashable.generate_hash(hash_representation)
+      end
+
+      def hash_representation
+        public_instance_variables.sort.to_h { |var| [var, instance_variable_get(var)] }
+      end
+
+      def self.generate_hash(obj)
+        Digest::MD5.hexdigest(hash_representation_recursive(obj).to_s)
+      end
+
+      def public_instance_variables
+        instance_variables.select do |var|
+          method_name = var.to_s.delete('@')
+          respond_to?(method_name) || respond_to?("#{method_name}=")
+        end
+      end
+
+      def self.hash_representation_recursive(obj)
+        case obj
+        when Hash
+          obj.transform_values { |v| hash_representation_recursive(v) }
+        when Array
+          obj.map { |v| hash_representation_recursive(v) }
+        when Hashable
+          obj.hash_representation
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/oas_rails/{info.rb → spec/info.rb}

@@ -1,28 +1,33 @@
 module OasRails
-  class Info < OasBase
-    attr_accessor :title, :summary, :description, :terms_of_service, :contact, :license, :version
-
-    def initialize(**kwargs)
-      super()
-      @title = kwargs[:title] || default_title
-      @summary = kwargs[:summary] || default_summary
-      @description = kwargs[:description] || default_description
-      @terms_of_service = kwargs[:terms_of_service] || ''
-      @contact = Contact.new
-      @license = License.new
-      @version = kwargs[:version] || '0.0.1'
-    end
-
-    def default_title
-      "OasRails #{VERSION}"
-    end
-
-    def default_summary
-      "OasRails: Automatic Interactive API Documentation for Rails"
-    end
-
-    def default_description
-      "# Welcome to OasRails
+  module Spec
+    class Info
+      include Specable
+      attr_accessor :title, :summary, :description, :terms_of_service, :contact, :license, :version
+
+      def initialize(**kwargs)
+        @title = kwargs[:title] || default_title
+        @summary = kwargs[:summary] || default_summary
+        @description = kwargs[:description] || default_description
+        @terms_of_service = kwargs[:terms_of_service] || ''
+        @contact = Spec::Contact.new
+        @license = Spec::License.new
+        @version = kwargs[:version] || '0.0.1'
+      end
+
+      def oas_fields
+        [:title, :summary, :description, :terms_of_service, :contact, :license, :version]
+      end
+
+      def default_title
+        "OasRails #{VERSION}"
+      end
+
+      def default_summary
+        "OasRails: Automatic Interactive API Documentation for Rails"
+      end
+
+      def default_description
+        "# Welcome to OasRails
 
 OasRails automatically generates interactive documentation for your Rails APIs using the OpenAPI Specification 3.1 (OAS 3.1) and displays it with a nice UI.
 
@@ -55,6 +60,7 @@ Explore your API documentation and enjoy the power of OasRails!
 For more information and advanced usage, visit the [OasRails GitHub repository](https://github.com/a-chacon/oas_rails).
 
       "
+      end
     end
   end
 end

data/lib/oas_rails/spec/license.rb

@@ -0,0 +1,18 @@
+module OasRails
+  module Spec
+    class License
+      include Specable
+
+      attr_accessor :name, :url
+
+      def initialize(**kwargs)
+        @name = kwargs[:name] || 'GPL 3.0'
+        @url = kwargs[:url] || 'https://www.gnu.org/licenses/gpl-3.0.html#license-text'
+      end
+
+      def oas_fields
+        [:name, :url]
+      end
+    end
+  end
+end