oas_core 0.0.1

data/lib/oas_core/spec/specable.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OasCore
+  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)
+                            #   hash = {}
+                            #   value.each do |key, object|
+                            #     hash[key] = object.to_spec
+                            #   end
+                            #   hash
+                            else
+                              value
+                            end
+
+          hash[camel_case_key] = processed_value unless valid_processed_value?(processed_value)
+        end
+        hash
+      end
+
+      # rubocop:disable Lint/UnusedMethodArgument
+      def as_json(options = nil)
+        to_spec
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+
+      private
+
+      def valid_processed_value?(processed_value)
+        ((processed_value.is_a?(Hash) || processed_value.is_a?(Array)) && processed_value.empty?) || processed_value.nil?
+      end
+
+      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_core/spec/specification.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module OasCore
+  module Spec
+    class Specification
+      include Specable
+      attr_accessor :components, :info, :openapi, :servers, :tags, :external_docs, :paths
+
+      def initialize
+        @components = Components.new(self)
+        @info = OasCore.config.info
+        @openapi = '3.1.0'
+        @servers = OasCore.config.servers
+        @tags = OasCore.config.tags
+        @external_docs = {}
+        @paths = Spec::Paths.new(self)
+      end
+
+      def oas_fields
+        %i[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 OasCore.config.authenticate_all_routes_by_default
+
+        OasCore.config.security_schemas.map { |key, _| { key => [] } }
+      end
+    end
+  end
+end

data/lib/oas_core/spec/tag.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Spec
+    class Tag
+      include Specable
+
+      attr_accessor :name, :description
+
+      def initialize(name:, description:)
+        @name = name.titleize
+        @description = description
+      end
+
+      def oas_fields
+        %i[name description]
+      end
+    end
+  end
+end

data/lib/oas_core/string.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class String
+  def squish
+    dup.squish!
+  end
+
+  def squish!
+    gsub!(/[[:space:]]+/, ' ')
+    strip!
+    self
+  end
+end

data/lib/oas_core/utils.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Utils
+    TYPE_MAPPING = {
+      'String' => 'string',
+      'Integer' => 'number',
+      'Float' => 'number',
+      'TrueClass' => 'boolean',
+      'FalseClass' => 'boolean',
+      'Boolean' => 'boolean',
+      'NilClass' => 'null',
+      'Hash' => 'object',
+      'Object' => 'object',
+      'DateTime' => 'string'
+    }.freeze
+
+    STATUS_SYMBOL_MAPPING = {
+      ok: 200,
+      created: 201,
+      no_content: 204,
+      bad_request: 400,
+      unauthorized: 401,
+      forbidden: 403,
+      not_found: 404,
+      unprocessable_entity: 422,
+      internal_server_error: 500
+    }.freeze
+
+    HTTP_STATUS_DEFINITIONS = {
+      200 => 'The request has succeeded.',
+      201 => 'The request has been fulfilled and resulted in a new resource being created.',
+      404 => 'The requested resource could not be found.',
+      401 => 'You are not authorized to access this resource. You need to authenticate yourself first.',
+      403 => 'You are not allowed to access this resource. You do not have the necessary permissions.',
+      500 => 'An unexpected error occurred on the server. The server was unable to process the request.',
+      422 => 'The server could not process the request due to semantic errors. Please check your input and try again.'
+    }.freeze
+
+    class << self
+      def hash_to_json_schema(hash)
+        {
+          type: 'object',
+          properties: hash_to_properties(hash),
+          required: []
+        }
+      end
+
+      def hash_to_properties(hash)
+        hash.transform_values do |value|
+          if value.is_a?(Hash)
+            hash_to_json_schema(value)
+          elsif value.is_a?(Class)
+            { type: ruby_type_to_json_type(value.name) }
+          else
+            { type: ruby_type_to_json_type(value.class.name) }
+          end
+        end
+      end
+
+      def ruby_type_to_json_type(ruby_type)
+        TYPE_MAPPING.fetch(ruby_type, 'string')
+      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_SYMBOL_MAPPING.fetch(status.to_sym) do
+            raise ArgumentError, "Unknown status symbol: #{status}"
+          end
+        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 get_definition(status_code)
+        HTTP_STATUS_DEFINITIONS[status_code] || "Definition not found for status code #{status_code}"
+      end
+
+      def class_to_symbol(klass)
+        klass.name.underscore.to_sym
+      end
+    end
+  end
+end

data/lib/oas_core/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OasCore
+  VERSION = '0.0.1'
+end

data/lib/oas_core/yard/example_tag.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class ExampleTag < ::YARD::Tags::Tag
+      attr_accessor :content
+
+      def initialize(tag_name, text, content: {})
+        super(tag_name, text, nil, nil)
+        @content = content
+      end
+    end
+  end
+end

data/lib/oas_core/yard/oas_core_factory.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class OasCoreFactory < ::YARD::Tags::DefaultFactory
+      # Parses a tag that represents a request body.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [RequestBodyTag] The parsed request body tag object.
+      def parse_tag_with_request_body(tag_name, text)
+        description, klass, schema, required = extract_description_and_schema(text.squish)
+        RequestBodyTag.new(tag_name, description, klass, schema:, required:)
+      end
+
+      # Parses a tag that represents a request body example.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [RequestBodyExampleTag] The parsed request body example tag object.
+      def parse_tag_with_request_body_example(tag_name, text)
+        description, _, hash = extract_description_type_and_content(text.squish, process_content: true,
+                                                                                 expresion: /^(.*?)\[([^\]]*)\](.*)$/m)
+        RequestBodyExampleTag.new(tag_name, description, content: hash)
+      end
+
+      # Parses a tag that represents a parameter.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [ParameterTag] The parsed parameter tag object.
+      def parse_tag_with_parameter(tag_name, text)
+        name, location, schema, required, description = extract_name_location_schema_and_description(text.squish)
+        name = "#{name}[]" if location == 'query' && schema[:type] == 'array'
+        ParameterTag.new(tag_name, name, description, schema, location, required:)
+      end
+
+      # Parses a tag that represents a response.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [ResponseTag] The parsed response tag object.
+      def parse_tag_with_response(tag_name, text)
+        name, code, schema = extract_name_code_and_schema(text.squish)
+        ResponseTag.new(tag_name, code, name, schema)
+      end
+
+      # Parses a tag that represents a response example.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [ResponseExampleTag] The parsed response example tag object.
+      def parse_tag_with_response_example(tag_name, text)
+        description, code, hash = extract_name_code_and_hash(text.squish)
+        ResponseExampleTag.new(tag_name, description, content: hash, code:)
+      end
+
+      private
+
+      # Reusable method for extracting description, type, and content with an option to process content.
+      # @param text [String] The text to parse.
+      # @param process_content [Boolean] Whether to evaluate the content as a hash.
+      # @return [Array] An array containing the description, type, and content or remaining text.
+      def extract_description_type_and_content(text, process_content: false, expresion: /^(.*?)\s*\[(.*)\]\s*(.*)$/)
+        match = text.match(expresion)
+        raise ArgumentError, "Invalid tag format: #{text}" if match.nil?
+
+        description = match[1].strip
+        type = match[2].strip
+        content = process_content ? eval_content(match[3].strip) : match[3].strip
+
+        [description, type, content]
+      end
+
+      # Specific method to extract description and schema for request body tags.
+      # @param text [String] The text to parse.
+      # @return [Array] An array containing the description, class, schema, and required flag.
+      def extract_description_and_schema(text)
+        description, type, = extract_description_type_and_content(text)
+        klass, schema, required = type_text_to_schema(type)
+        [description, klass, schema, required]
+      end
+
+      # Specific method to extract name, location, and schema for parameters.
+      # @param text [String] The text to parse.
+      # @return [Array] An array containing the name, location, schema, and required flag.
+      def extract_name_location_schema_and_description(text)
+        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
+        name, location = extract_text_and_parentheses_content(match[1].strip)
+        schema, required = type_text_to_schema(match[2].strip)[1..]
+        description = match[3].strip
+        [name, location, schema, required, description]
+      end
+
+      # Specific method to extract name, code, and schema for responses.
+      # @param text [String] The text to parse.
+      # @return [Array] An array containing the name, code, and schema.
+      def extract_name_code_and_schema(text)
+        name, code = extract_text_and_parentheses_content(text)
+        _, type, = extract_description_type_and_content(text)
+        schema = type_text_to_schema(type)[1]
+        [name, code, schema]
+      end
+
+      # Specific method to extract name, code, and hash for responses examples.
+      # @param text [String] The text to parse.
+      # @return [Array] An array containing the name, code, and schema.
+      def extract_name_code_and_hash(text)
+        name, code = extract_text_and_parentheses_content(text)
+        _, _, content = extract_description_type_and_content(text, expresion: /^(.*?)\[([^\]]*)\](.*)$/m)
+        hash = eval_content(content)
+        [name, code, hash]
+      end
+
+      # Evaluates a string as a hash, handling errors gracefully.
+      # @param content [String] The content string to evaluate.
+      # @return [Hash] The evaluated hash, or an empty hash if an error occurs.
+      # rubocop:disable Security/Eval
+      def eval_content(content)
+        eval(content)
+      rescue StandardError
+        {}
+      end
+      # rubocop:enable Security/Eval
+
+      # Parses the position name and location from input text.
+      # @param input [String] The input text to parse.
+      # @return [Array] An array containing the name and location.
+      def extract_text_and_parentheses_content(input)
+        return unless input =~ /^(.+?)\(([^)]+)\)/
+
+        text = ::Regexp.last_match(1).strip
+        parenthesis_content = ::Regexp.last_match(2).strip
+        [text, parenthesis_content]
+      end
+
+      # Extracts the text and whether it's required.
+      # @param text [String] The text to parse.
+      # @return [Array] An array containing the text and a required flag.
+      def text_and_required(text)
+        if text.start_with?('!')
+          [text.sub(/^!/, ''), true]
+        else
+          [text, false]
+        end
+      end
+
+      # Matches and validates a description and type from text.
+      # @param text [String] The text to parse.
+      # @return [MatchData] The match data from the regex.
+      def description_and_type(text)
+        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
+        raise ArgumentError, "The request body tag is not valid: #{text}" if match.nil?
+
+        match
+      end
+
+      # Converts type text to a schema, checking if it's an ActiveRecord class.
+      # @param text [String] The type text to convert.
+      # @return [Array] An array containing the class, schema, and required flag.
+      def type_text_to_schema(text)
+        type_text, required = text_and_required(text)
+
+        schema = JsonSchemaGenerator.process_string(type_text)[:json_schema]
+        klass = Object
+
+        [klass, schema, required]
+      end
+    end
+  end
+end

data/lib/oas_core/yard/parameter_tag.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class ParameterTag < ::YARD::Tags::Tag
+      attr_accessor :schema, :required, :location
+
+      def initialize(tag_name, name, text, schema, location, required: false)
+        super(tag_name, text, nil, name)
+        @schema = schema
+        @required = required
+        @location = location
+      end
+    end
+  end
+end

data/lib/oas_core/yard/request_body_example_tag.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class RequestBodyExampleTag < ExampleTag
+      attr_accessor :content
+
+      def initialize(tag_name, text, content: {})
+        super
+      end
+    end
+  end
+end

data/lib/oas_core/yard/request_body_tag.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class RequestBodyTag < ::YARD::Tags::Tag
+      attr_accessor :klass, :schema, :required
+
+      def initialize(tag_name, text, klass, schema: {}, required: false)
+        # initialize(tag_name, text, types = nil, name = nil)
+        super(tag_name, text, nil, nil)
+        @klass = klass
+        @schema = schema
+        @required = required
+      end
+    end
+  end
+end

data/lib/oas_core/yard/response_example_tag.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class ResponseExampleTag < ExampleTag
+      attr_accessor :code
+
+      def initialize(tag_name, text, content: {}, code: 200)
+        super(tag_name, text, content:)
+        @code = code
+      end
+    end
+  end
+end

data/lib/oas_core/yard/response_tag.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OasCore
+  module YARD
+    class ResponseTag < ::YARD::Tags::Tag
+      attr_accessor :schema
+
+      # TODO: name == code. The name MUST be changed to code for better understanding
+      def initialize(tag_name, name, text, schema)
+        super(tag_name, text, nil, name)
+        @schema = schema
+      end
+    end
+  end
+end

data/lib/oas_core.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'yard'
+require 'method_source'
+require 'oas_core/string'
+
+module OasCore
+  require 'oas_core/version'
+
+  autoload :Configuration, 'oas_core/configuration'
+  autoload :OasRoute, 'oas_core/oas_route'
+  autoload :Utils, 'oas_core/utils'
+  autoload :JsonSchemaGenerator, 'oas_core/json_schema_generator'
+
+  module Builders
+    autoload :OperationBuilder, 'oas_core/builders/operation_builder'
+    autoload :PathItemBuilder, 'oas_core/builders/path_item_builder'
+    autoload :ResponseBuilder, 'oas_core/builders/response_builder'
+    autoload :ResponsesBuilder, 'oas_core/builders/responses_builder'
+    autoload :ContentBuilder, 'oas_core/builders/content_builder'
+    autoload :ParametersBuilder, 'oas_core/builders/parameters_builder'
+    autoload :ParameterBuilder, 'oas_core/builders/parameter_builder'
+    autoload :RequestBodyBuilder, 'oas_core/builders/request_body_builder'
+    autoload :OasRouteBuilder, 'oas_core/builders/oas_route_builder'
+    autoload :SpecificationBuilder, 'oas_core/builders/specification_builder'
+  end
+
+  module Spec
+    autoload :Hashable, 'oas_core/spec/hashable'
+    autoload :Specable, 'oas_core/spec/specable'
+    autoload :Components, 'oas_core/spec/components'
+    autoload :Parameter, 'oas_core/spec/parameter'
+    autoload :License, 'oas_core/spec/license'
+    autoload :Response, 'oas_core/spec/response'
+    autoload :PathItem, 'oas_core/spec/path_item'
+    autoload :Operation, 'oas_core/spec/operation'
+    autoload :RequestBody, 'oas_core/spec/request_body'
+    autoload :Responses, 'oas_core/spec/responses'
+    autoload :MediaType, 'oas_core/spec/media_type'
+    autoload :Paths, 'oas_core/spec/paths'
+    autoload :Contact, 'oas_core/spec/contact'
+    autoload :Info, 'oas_core/spec/info'
+    autoload :Server, 'oas_core/spec/server'
+    autoload :Tag, 'oas_core/spec/tag'
+    autoload :Specification, 'oas_core/spec/specification'
+    autoload :Reference, 'oas_core/spec/reference'
+  end
+
+  module YARD
+    autoload :RequestBodyTag, 'oas_core/yard/request_body_tag'
+    autoload :ExampleTag, 'oas_core/yard/example_tag'
+    autoload :RequestBodyExampleTag, 'oas_core/yard/request_body_example_tag'
+    autoload :ParameterTag, 'oas_core/yard/parameter_tag'
+    autoload :ResponseTag, 'oas_core/yard/response_tag'
+    autoload :ResponseExampleTag, 'oas_core/yard/response_example_tag'
+    autoload :OasCoreFactory, 'oas_core/yard/oas_core_factory'
+  end
+
+  class << self
+    def configure
+      OasCore.configure_yard!
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure_yard!
+      ::YARD::Tags::Library.default_factory = YARD::OasCoreFactory
+      yard_tags = {
+        'Request body' => %i[request_body with_request_body],
+        'Request body Example' => %i[request_body_example with_request_body_example],
+        'Parameter' => %i[parameter with_parameter],
+        'Response' => %i[response with_response],
+        'Response Example' => %i[response_example with_response_example],
+        'Endpoint Tags' => [:tags],
+        'Summary' => [:summary],
+        'No Auth' => [:no_auth],
+        'Auth methods' => %i[auth with_types],
+        'OAS Include' => [:oas_include]
+      }
+      yard_tags.each do |tag_name, (method_name, handler)|
+        ::YARD::Tags::Library.define_tag(tag_name, method_name, handler)
+      end
+    end
+  end
+end