oas_rails 0.3.0 → 0.4.0

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

data/lib/oas_rails/spec/media_type.rb

@@ -0,0 +1,84 @@
+module OasRails
+  module Spec
+    class MediaType
+      include Specable
+
+      attr_accessor :schema, :example, :examples, :encoding
+
+      @context = :incoming
+      @factory_examples = {}
+
+      # Initializes a new MediaType object.
+      #
+      # @param schema [Hash] the schema of the media type.
+      # @param kwargs [Hash] additional keyword arguments.
+      def initialize(specification)
+        @specification = specification
+        @schema = {}
+        @example =  {}
+        @examples = {}
+      end
+
+      def oas_fields
+        [:schema, :example, :examples, :encoding]
+      end
+
+      class << self
+        # Searches for examples in test files based on the provided class and test framework.
+        #
+        # @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.
+        def search_for_examples_in_tests(klass, context: :incoming, utils: Utils)
+          @context = context
+          case utils.detect_test_framework
+          when :factory_bot
+            fetch_factory_bot_examples(klass:)
+          when :fixtures
+            fetch_fixture_examples(klass:)
+          else
+            {}
+          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 = Utils.class_to_symbol(klass)
+
+          begin
+            @factory_examples[klass_sym] = FactoryBot.build_stubbed_list(klass_sym, 1) if @factory_examples[klass_sym].nil?
+
+            @factory_examples[klass_sym].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
+end

data/lib/oas_rails/spec/operation.rb

@@ -0,0 +1,25 @@
+module OasRails
+  module Spec
+    class Operation
+      include Specable
+
+      attr_accessor :specification, :tags, :summary, :description, :operation_id, :parameters, :request_body, :responses, :security
+
+      def initialize(specification)
+        @specification = specification
+        @summary = ""
+        @operation_id = ""
+        @tags = []
+        @description = @summary
+        @parameters = []
+        @request_body = {}
+        @responses =  Spec::Responses.new(specification)
+        @security = []
+      end
+
+      def oas_fields
+        [:tags, :summary, :description, :operation_id, :parameters, :request_body, :responses, :security]
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/parameter.rb

@@ -0,0 +1,34 @@
+module OasRails
+  module Spec
+    class Parameter
+      include Specable
+      include Hashable
+
+      STYLE_DEFAULTS = { query: 'form', path: 'simple', header: 'simple', cookie: 'form' }.freeze
+
+      attr_accessor :name, :in, :style, :description, :required, :schema
+
+      def initialize(specification)
+        @specification = specification
+        @name = ""
+        @in = ""
+        @description = ""
+        @required = false
+        @style = ""
+        @schema = { type: 'string' }
+      end
+
+      def default_from_in
+        STYLE_DEFAULTS[@in.to_sym]
+      end
+
+      def required?
+        @in == 'path'
+      end
+
+      def oas_fields
+        [:name, :in, :description, :required, :schema, :style]
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/path_item.rb

@@ -0,0 +1,33 @@
+module OasRails
+  module Spec
+    class PathItem
+      include Specable
+      attr_reader :get, :post, :put, :patch, :delete
+
+      def initialize(specification)
+        @specification = specification
+        @get = nil
+        @post = nil
+        @put = nil
+        @patch = nil
+        @delete = nil
+      end
+
+      def fill_from(path, route_extractor: Extractors::RouteExtractor)
+        route_extractor.host_routes_by_path(path).each do |oas_route|
+          add_operation(oas_route.verb.downcase, Spec::Operation.new(@specification).fill_from(oas_route))
+        end
+
+        self
+      end
+
+      def add_operation(http_method, operation)
+        instance_variable_set("@#{http_method}", operation)
+      end
+
+      def oas_fields
+        [:get, :post, :put, :patch, :delete]
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/paths.rb

@@ -0,0 +1,26 @@
+module OasRails
+  module Spec
+    class Paths
+      include Specable
+
+      attr_accessor :path_items
+
+      def initialize(specification)
+        @specification = specification
+        @path_items = {}
+      end
+
+      def add_path(path)
+        @path_items[path] = Builders::PathItemBuilder.new(@specification).from_path(path).build
+      end
+
+      def to_spec
+        paths_hash = {}
+        @path_items.each do |path, path_object|
+          paths_hash[path] = path_object.to_spec
+        end
+        paths_hash
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/reference.rb

@@ -0,0 +1,16 @@
+module OasRails
+  module Spec
+    class Reference
+      include Specable
+      attr_reader :ref
+
+      def initialize(ref)
+        @ref = ref
+      end
+
+      def to_spec
+        { '$ref' => @ref }
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/request_body.rb

@@ -0,0 +1,21 @@
+module OasRails
+  module Spec
+    class RequestBody
+      include Specable
+      include Hashable
+
+      attr_accessor :description, :content, :required
+
+      def initialize(specification)
+        @specification = specification
+        @description = ""
+        @content = {} # a hash with media type objects
+        @required = false
+      end
+
+      def oas_fields
+        [:description, :content, :required]
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/response.rb

@@ -0,0 +1,20 @@
+module OasRails
+  module Spec
+    class Response
+      include Specable
+      include Hashable
+
+      attr_accessor :code, :description, :content
+
+      def initialize(specification)
+        @specification = specification
+        @description = ""
+        @content = {} # Hash with {content: MediaType}
+      end
+
+      def oas_fields
+        [:description, :content]
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/responses.rb

@@ -0,0 +1,25 @@
+module OasRails
+  module Spec
+    class Responses
+      include Specable
+      attr_accessor :responses
+
+      def initialize(specification)
+        @specification = specification
+        @responses = {}
+      end
+
+      def add_response(response)
+        @responses[response.code] = @specification.components.add_response(response)
+      end
+
+      def to_spec
+        spec = {}
+        @responses.each do |key, value|
+          spec[key] = value.to_spec
+        end
+        spec
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/server.rb

@@ -0,0 +1,17 @@
+module OasRails
+  module Spec
+    class Server
+      include Specable
+      attr_accessor :url, :description
+
+      def initialize(url:, description:)
+        @url = url
+        @description = description
+      end
+
+      def oas_fields
+        [:url, :description]
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/specable.rb

@@ -0,0 +1,51 @@
+module OasRails
+  module Spec
+    module Specable
+      def oas_fields
+        []
+      end
+
+      def to_spec
+        hash = {}
+        oas_fields.each do |var|
+          key = var.to_s
+
+          camel_case_key = key.camelize(:lower).to_sym
+          value = send(var)
+
+          processed_value = if value.respond_to?(:to_spec)
+                              value.to_spec
+                            elsif value.is_a?(Array) && value.all? { |elem| elem.respond_to?(:to_spec) }
+                              value.map(&:to_spec)
+                            # elsif value.is_a?(Hash)
+                            #   p "Here"
+                            #   p value
+                            #   hash = {}
+                            #   value.each do |key, object|
+                            #     hash[key] = object.to_spec
+                            #   end
+                            #   hash
+                            else
+                              value
+                            end
+
+          # hash[camel_case_key] = processed_value unless (processed_value.is_a?(Hash) || processed_value.is_a?(Array)) && processed_value.empty?
+          hash[camel_case_key] = processed_value unless processed_value.nil?
+        end
+        hash
+      end
+
+      def as_json
+        to_spec
+      end
+
+      private
+
+      def snake_to_camel(snake_str)
+        words = snake_str.to_s.split('_')
+        words[1..].map!(&:capitalize)
+        (words[0] + words[1..].join).to_sym
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/specification.rb

@@ -0,0 +1,50 @@
+require 'json'
+
+module OasRails
+  module Spec
+    class Specification
+      include Specable
+      attr_accessor :components, :info, :openapi, :servers, :tags, :external_docs, :paths
+
+      # Initializes a new Specification object.
+      # Clears the cache if running in the development environment.
+      def initialize
+        clear_cache unless Rails.env.production?
+
+        @components = Components.new(self)
+        @info = OasRails.config.info
+        @openapi = '3.1.0'
+        @servers = OasRails.config.servers
+        @tags = OasRails.config.tags
+        @external_docs = {}
+        @paths = Spec::Paths.new(self)
+      end
+
+      def build(route_extractor: Extractors::RouteExtractor)
+        route_extractor.host_paths.each do |path|
+          @paths.add_path(path)
+        end
+      end
+
+      # Clears the cache for MethodSource and RouteExtractor.
+      #
+      # @return [void]
+      def clear_cache
+        MethodSource.clear_cache
+        Extractors::RouteExtractor.clear_cache
+      end
+
+      def oas_fields
+        [:openapi, :info, :servers, :paths, :components, :security, :tags, :external_docs]
+      end
+
+      # Create the Security Requirement Object.
+      # @see https://spec.openapis.org/oas/latest.html#security-requirement-object
+      def security
+        return [] unless OasRails.config.authenticate_all_routes_by_default
+
+        OasRails.config.security_schemas.map { |key, _| { key => [] } }
+      end
+    end
+  end
+end

data/lib/oas_rails/spec/tag.rb

@@ -0,0 +1,18 @@
+module OasRails
+  module Spec
+    class Tag
+      include Specable
+
+      attr_accessor :name, :description
+
+      def initialize(name:, description:)
+        @name = name.titleize
+        @description = description
+      end
+
+      def oas_fields
+        [:name, :description]
+      end
+    end
+  end
+end