oas_rails 0.2.3 → 0.4.0

data/lib/oas_rails/license.rb

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

data/lib/oas_rails/media_type.rb

@@ -1,76 +0,0 @@
-module OasRails
-  class MediaType < OasBase
-    attr_accessor :schema, :example, :examples, :encoding
-
-    def initialize(schema:, **kwargs)
-      super()
-      @schema = schema
-      @example = kwargs[:example] || {}
-      @examples = kwargs[:examples] || []
-    end
-
-    class << self
-      def from_model_class(klass:, examples: {})
-        return unless klass.ancestors.include? ActiveRecord::Base
-
-        model_schema = Esquema::Builder.new(klass).build_schema.as_json
-        model_schema["required"] = []
-        schema = { type: "object", properties: { klass.to_s.downcase => model_schema } }
-        examples.merge!(search_for_examples_in_tests(klass:))
-        new(media_type: "", schema:, examples:)
-      end
-
-      # 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
-          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 } } }
-        else
-          {}
-        end
-      end
-
-      def tags_to_examples(tags:)
-        tags.each_with_object({}).with_index(1) do |(example, result), _index|
-          key = example.text.downcase.gsub(' ', '_')
-          value = {
-            "summary" => example.text,
-            "value" => example.content
-          }
-          result[key] = value
-        end
-      end
-    end
-  end
-end

data/lib/oas_rails/oas_base.rb

@@ -1,30 +0,0 @@
-module OasRails
-  class OasBase
-    def to_spec
-      hash = {}
-      instance_variables.each do |var|
-        key = var.to_s.delete('@')
-        camel_case_key = key.camelize(:lower).to_sym
-        value = instance_variable_get(var)
-
-        processed_value = if value.respond_to?(:to_spec)
-                            value.to_spec
-                          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
-      end
-      hash
-    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

data/lib/oas_rails/operation.rb

@@ -1,134 +0,0 @@
-module OasRails
-  class Operation < OasBase
-    attr_accessor :tags, :summary, :description, :operation_id, :parameters, :method, :docstring, :request_body, :responses, :security
-
-    def initialize(method:, summary:, operation_id:, **kwargs)
-      super()
-      @method = method
-      @summary = summary
-      @operation_id = operation_id
-      @tags = kwargs[:tags] || []
-      @description = kwargs[:description] || @summary
-      @parameters = kwargs[:parameters] || []
-      @request_body = kwargs[:request_body] || {}
-      @responses = kwargs[:responses] || {}
-      @security = kwargs[:security] || []
-    end
-
-    class << self
-      def from_oas_route(oas_route:)
-        summary = extract_summary(oas_route:)
-        operation_id = extract_operation_id(oas_route:)
-        tags = extract_tags(oas_route:)
-        description = oas_route.docstring
-        parameters = extract_parameters(oas_route:)
-        request_body = extract_request_body(oas_route:)
-        responses = extract_responses(oas_route:)
-        security = extract_security(oas_route:)
-        new(method: oas_route.verb.downcase, summary:, operation_id:, tags:, description:, parameters:, request_body:, responses:, security:)
-      end
-
-      def extract_summary(oas_route:)
-        oas_route.docstring.tags(:summary).first.try(:text) || generate_crud_name(oas_route.method, oas_route.controller.downcase) || oas_route.verb + " " + oas_route.path
-      end
-
-      def generate_crud_name(method, controller)
-        controller_name = controller.to_s.underscore.humanize.downcase.pluralize
-
-        case method.to_sym
-        when :index
-          "List #{controller_name}"
-        when :show
-          "View #{controller_name.singularize}"
-        when :create
-          "Create new #{controller_name.singularize}"
-        when :update
-          "Update #{controller_name.singularize}"
-        when :destroy
-          "Delete #{controller_name.singularize}"
-        end
-      end
-
-      def extract_operation_id(oas_route:)
-        "#{oas_route.method}#{oas_route.path.gsub('/', '_').gsub(/[{}]/, '')}"
-      end
-
-      # This method should check tags defined by yard, then extract tag from path namespace or controller name depending on configuration
-      def extract_tags(oas_route:)
-        tags = oas_route.docstring.tags(:tags).first
-        if !tags.nil?
-          tags.text.split(",").map(&:strip).map(&:titleize)
-        else
-          default_tags(oas_route:)
-        end
-      end
-
-      def default_tags(oas_route:)
-        tags = []
-        if OasRails.config.default_tags_from == "namespace"
-          tag = oas_route.path.split('/').reject(&:empty?).first.try(:titleize)
-          tags << tag unless tag.nil?
-        else
-          tags << oas_route.controller.titleize
-        end
-        tags
-      end
-
-      def extract_parameters(oas_route:)
-        parameters = []
-        parameters.concat(parameters_from_tags(tags: oas_route.docstring.tags(:parameter)))
-        oas_route.path_params.try(:map) do |p|
-          parameters << Parameter.from_path(path: oas_route.path, param: p) unless parameters.any? { |param| param.name.to_s == p.to_s }
-        end
-        parameters
-      end
-
-      def parameters_from_tags(tags:)
-        tags.map do |t|
-          Parameter.new(name: t.name, location: t.location, required: t.required, schema: t.schema, description: t.text)
-        end
-      end
-
-      def extract_request_body(oas_route:)
-        tag_request_body = oas_route.docstring.tags(:request_body).first
-        if tag_request_body.nil? && OasRails.config.autodiscover_request_body
-          oas_route.detect_request_body if %w[create update].include? oas_route.method
-        elsif !tag_request_body.nil?
-          RequestBody.from_tags(tag: tag_request_body, examples_tags: oas_route.docstring.tags(:request_body_example))
-        else
-          {}
-        end
-      end
-
-      def extract_responses(oas_route:)
-        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.each do |new_response|
-            responses.responses << new_response unless responses.responses.any? { |r| r.code == new_response.code }
-          end
-        end
-
-        responses
-      end
-
-      def extract_security(oas_route:)
-        return [] if oas_route.docstring.tags(:no_auth).any?
-
-        if (methods = oas_route.docstring.tags(:auth).first)
-          OasRails.config.security_schemas.keys.map { |key| { key => [] } }.select do |schema|
-            methods.types.include?(schema.keys.first.to_s)
-          end
-        elsif OasRails.config.authenticate_all_routes_by_default
-          OasRails.config.security_schemas.keys.map { |key| { key => [] } }
-        else
-          []
-        end
-      end
-
-      def external_docs; end
-    end
-  end
-end

data/lib/oas_rails/parameter.rb

@@ -1,47 +0,0 @@
-module OasRails
-  class Parameter
-    STYLE_DEFAULTS = { query: 'form', path: 'simple', header: 'simple', cookie: 'form' }.freeze
-
-    attr_accessor :name, :in, :style, :description, :required, :schema
-
-    def initialize(name:, location:, description:, **kwargs)
-      @name = name
-      @in = location
-      @description = description
-
-      @required = kwargs[:required] || required?
-      @style = kwargs[:style] || default_from_in
-      @schema = kwargs[:schema] || { "type": 'string' }
-    end
-
-    def self.from_path(path:, param:)
-      new(name: param, location: 'path',
-          description: "#{param.split('_')[-1].titleize} of existing #{extract_word_before(path, param).singularize}.")
-    end
-
-    def self.extract_word_before(string, param)
-      regex = %r{/(\w+)/\{#{param}\}}
-      match = string.match(regex)
-      match ? match[1] : nil
-    end
-
-    def default_from_in
-      STYLE_DEFAULTS[@in.to_sym]
-    end
-
-    def required?
-      @in == 'path'
-    end
-
-    def to_spec
-      {
-        "name": @name,
-        "in": @in,
-        "description": @description,
-        "required": @required,
-        "schema": @schema,
-        "style": @style
-      }
-    end
-  end
-end

data/lib/oas_rails/path_item.rb

@@ -1,25 +0,0 @@
-module OasRails
-  class PathItem
-    attr_reader :path, :operations, :parameters
-
-    def initialize(path:, operations:, parameters:)
-      @path = path
-      @operations = operations
-      @parameters = parameters
-    end
-
-    def self.from_oas_routes(path:, oas_routes:)
-      new(path: path, operations: oas_routes.map do |oas_route|
-                                    Operation.from_oas_route(oas_route: oas_route)
-                                  end, parameters: [])
-    end
-
-    def to_spec
-      spec = {}
-      @operations.each do |o|
-        spec[o.method] = o.to_spec
-      end
-      spec
-    end
-  end
-end

data/lib/oas_rails/paths.rb

@@ -1,19 +0,0 @@
-module OasRails
-  class Paths
-    attr_accessor :path_items
-
-    def initialize(path_items:)
-      @path_items = path_items
-    end
-
-    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))
-                      end)
-    end
-
-    def to_spec
-      @path_items.each_with_object({}) { |p, object| object[p.path] = p.to_spec }
-    end
-  end
-end

data/lib/oas_rails/request_body.rb

@@ -1,29 +0,0 @@
-module OasRails
-  class RequestBody < OasBase
-    attr_accessor :description, :content, :required
-
-    def initialize(description:, content:, required: false)
-      super()
-      @description = description
-      @content = content # Should be an array of media type object
-      @required = required
-    end
-
-    class << self
-      def from_tags(tag:, examples_tags: [])
-        if tag.klass.ancestors.include? ActiveRecord::Base
-          from_model_class(klass: tag.klass, description: tag.text, required: tag.required, examples_tags:)
-        else
-          # hash content to schema
-          content = { "application/json": MediaType.new(schema: tag.schema, examples: MediaType.tags_to_examples(tags: examples_tags)) }
-          new(description: tag.text, content:, required: tag.required)
-        end
-      end
-
-      def from_model_class(klass:, **kwargs)
-        content = { "application/json": MediaType.from_model_class(klass:, examples: MediaType.tags_to_examples(tags: kwargs[:examples_tags] || {})) }
-        new(description: kwargs[:description] || klass.to_s, content:, required: kwargs[:required])
-      end
-    end
-  end
-end

data/lib/oas_rails/response.rb

@@ -1,12 +0,0 @@
-module OasRails
-  class Response < OasBase
-    attr_accessor :code, :description, :content
-
-    def initialize(code:, description:, content:)
-      super()
-      @code = code
-      @description = description
-      @content = content # Should be an array of media type object
-    end
-  end
-end

data/lib/oas_rails/responses.rb

@@ -1,20 +0,0 @@
-module OasRails
-  class Responses < OasBase
-    attr_accessor :responses
-
-    def initialize(responses)
-      super()
-      @responses = responses
-    end
-
-    def to_spec
-      @responses.each_with_object({}) { |r, object| object[r.code] = r.to_spec }
-    end
-
-    class << self
-      def from_tags(tags:)
-        new(tags.map { |t| Response.new(code: t.name.to_i, description: t.text, content: { "application/json": MediaType.new(schema: t.schema) }) })
-      end
-    end
-  end
-end

data/lib/oas_rails/route_extractor.rb

@@ -1,119 +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
-
-      # 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
-        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

data/lib/oas_rails/server.rb

@@ -1,10 +0,0 @@
-module OasRails
-  class Server < OasBase
-    attr_accessor :url, :description
-
-    def initialize(url:, description:)
-      @url = url
-      @description = description
-    end
-  end
-end

data/lib/oas_rails/specification.rb

@@ -1,72 +0,0 @@
-require 'json'
-
-module OasRails
-  class Specification
-    # Initializes a new Specification object.
-    # Clears the cache if running in the development environment.
-    def initialize
-      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
-      Rails.logger.error("Error Generating OAS: #{e.message}")
-      {}
-    end
-
-    # Create the Base of the OAS hash.
-    # @see https://spec.openapis.org/oas/latest.html#schema
-    def base_spec
-      {
-        openapi: '3.1.0',
-        info: OasRails.config.info.to_spec,
-        servers: OasRails.config.servers.map(&:to_spec),
-        paths:,
-        components:,
-        security:,
-        tags: OasRails.config.tags.map(&:to_spec),
-        externalDocs: {}
-      }
-    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
-
-    # 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
-    end
-
-    # Created the Components Object For the Root of the OAS.
-    # @see https://spec.openapis.org/oas/latest.html#components-object
-    def components
-      {
-        schemas: {}, parameters: {}, securitySchemes: security_schemas, requestBodies: {}, responses: {},
-        headers: {}, examples: {}, links: {}, callbacks: {}
-      }
-    end
-
-    # Create the Security Schemas Array inside components field of the OAS.
-    # @see https://spec.openapis.org/oas/latest.html#security-scheme-object
-    def security_schemas
-      OasRails.config.security_schemas
-    end
-  end
-end

data/lib/oas_rails/tag.rb

@@ -1,17 +0,0 @@
-module OasRails
-  class Tag
-    attr_accessor :name, :description
-
-    def initialize(name:, description:)
-      @name = name.titleize
-      @description = description
-    end
-
-    def to_spec
-      {
-        name: @name,
-        description: @description
-      }
-    end
-  end
-end