oas_core 0.0.1

data/lib/oas_core/json_schema_generator.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module OasCore
+  # The JsonSchemaGenerator module provides methods to transform string representations
+  # of data types into JSON schema formats.
+  module JsonSchemaGenerator
+    # Processes a string representing a data type and converts it into a JSON schema.
+    #
+    # @param str [String] The string representation of a data type.
+    # @return [Hash] A hash containing the required flag and the JSON schema.
+    def self.process_string(str)
+      parsed = parse_type(str)
+      {
+        required: parsed[:required],
+        json_schema: to_json_schema(parsed)
+      }
+    end
+
+    # Parses a string representing a data type and determines its JSON schema type.
+    #
+    # @param str [String] The string representation of a data type.
+    # @return [Hash] A hash containing the type, whether it's required, and any additional properties.
+    def self.parse_type(str)
+      required = str.start_with?('!')
+      type = str.sub(/^!/, '').strip
+
+      case type
+      when /^Hash\{(.+)\}$/i
+        { type: :object, required:, properties: parse_object_properties(::Regexp.last_match(1)) }
+      when /^Array<(.+)>$/i
+        { type: :array, required:, items: parse_type(::Regexp.last_match(1)) }
+      else
+        { type: type.downcase.to_sym, required: }
+      end
+    end
+
+    # Parses the properties of an object type from a string.
+    #
+    # @param str [String] The string representation of the object's properties.
+    # @return [Hash] A hash where keys are property names and values are their JSON schema types.
+    def self.parse_object_properties(str)
+      properties = {}
+      stack = []
+      current_key = ''
+      current_value = ''
+
+      str.each_char.with_index do |char, index|
+        case char
+        when '{', '<'
+          stack.push(char)
+          current_value += char
+        when '}', '>'
+          stack.pop
+          current_value += char
+        when ','
+          if stack.empty?
+            properties[current_key.strip.to_sym] = parse_type(current_value.strip)
+            current_key = ''
+            current_value = ''
+          else
+            current_value += char
+          end
+        when ':'
+          if stack.empty?
+            current_key = current_value
+            current_value = ''
+          else
+            current_value += char
+          end
+        else
+          current_value += char
+        end
+
+        if index == str.length - 1 && !current_key.empty?
+          properties[current_key.strip.to_sym] =
+            parse_type(current_value.strip)
+        end
+      end
+
+      properties
+    end
+
+    # Converts a parsed data type into a JSON schema format.
+    #
+    # @param parsed [Hash] The parsed data type hash.
+    # @return [Hash] The JSON schema representation of the parsed data type.
+    def self.to_json_schema(parsed)
+      case parsed[:type]
+      when :object
+        schema = {
+          type: 'object',
+          properties: {}
+        }
+        required_props = []
+        parsed[:properties].each do |key, value|
+          schema[:properties][key] = to_json_schema(value)
+          required_props << key.to_s if value[:required]
+        end
+        schema[:required] = required_props unless required_props.empty?
+        schema
+      when :array
+        {
+          type: 'array',
+          items: to_json_schema(parsed[:items])
+        }
+      when nil
+        parsed
+      else
+        ruby_type_to_json_schema_type(parsed[:type])
+      end
+    end
+
+    # Converts a Ruby data type into its corresponding JSON schema type.
+    #
+    # @param type [Symbol, String] The Ruby data type.
+    # @return [Hash, String] The JSON schema type or a hash with additional format information.
+    def self.ruby_type_to_json_schema_type(type)
+      case type.to_s.downcase
+      when 'string' then { type: 'string' }
+      when 'integer' then { type: 'integer' }
+      when 'float' then { type: 'float' }
+      when 'boolean' then { type: 'boolean' }
+      when 'array' then { type: 'array' }
+      when 'hash' then { type: 'hash' }
+      when 'nil' then { type: 'null' }
+      when 'date' then { type: 'string', format: 'date' }
+      when 'datetime' then { type: 'string', format: 'date-time' }
+      else type.to_s.downcase
+      end
+    end
+  end
+end

data/lib/oas_core/oas_route.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module OasCore
+  class OasRoute
+    # TODO: Check what variables are in use and remove the ones that are not.
+    attr_accessor :controller_class, :controller_action, :controller, :controller_path, :method_name, :verb, :path,
+                  :docstring, :source_string
+    attr_writer :tags
+
+    def initialize(attributes = {})
+      attributes.each { |key, value| send("#{key}=", value) }
+    end
+
+    def path_params
+      @path.to_s.scan(/:(\w+)/).flatten.reject! { |e| e == 'format' }
+    end
+
+    def tags(name = nil)
+      return @tags if name.nil?
+
+      @tags.select { |tag| tag.tag_name.to_s == name.to_s }
+    end
+  end
+end

data/lib/oas_core/spec/components.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module OasCore
+  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 = OasCore.config.security_schemas
+        @request_bodies = {}
+        @responses = {}
+        @headers = {}
+        @examples = {}
+        @links = {}
+        @callbacks = {}
+      end
+
+      def oas_fields
+        %i[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 = nil
+        if OasCore.config.use_model_names
+          if schema[:type] == 'array'
+            arr_schema = schema[:items]
+            arr_key = arr_schema['title']
+            key = "#{arr_key}List" unless arr_key.nil?
+          else
+            key = schema['title']
+          end
+        end
+
+        key = Hashable.generate_hash(schema) if key.nil?
+
+        @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_core/spec/contact.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OasCore
+  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
+        %i[name url email]
+      end
+    end
+  end
+end

data/lib/oas_core/spec/hashable.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OasCore
+  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_core/spec/info.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OasCore
+  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
+        %i[title summary description terms_of_service contact license version]
+      end
+
+      def default_title
+        "OasCore #{VERSION}"
+      end
+
+      def default_summary
+        'OasCore: Automatic Interactive API Documentation for Rails'
+      end
+
+      def default_description
+        "# Welcome to OasCore
+
+OasCore automatically generates interactive documentation for your Rails APIs using the OpenAPI Specification 3.1 (OAS 3.1) and displays it with a nice UI.
+
+## Getting Started
+
+You've successfully mounted the OasCore engine. This default documentation is based on your routes and automatically gathered information.
+
+## Enhancing Your Documentation
+
+To customize and enrich your API documentation:
+
+1. Generate an initializer file:
+
+  ```
+  rails generate oas_core:config
+  ```
+2. Edit the created `config/initializers/oas_core.rb` file to override default settings and add project-specific information.
+
+3. Use Yard tags in your controller methods to provide detailed API endpoint descriptions.
+
+## Features
+
+- Automatic OAS 3.1 document generation
+- [RapiDoc](https://github.com/rapi-doc/RapiDoc) integration for interactive exploration
+- Minimal setup required for basic documentation
+- Extensible through configuration and Yard tags
+
+Explore your API documentation and enjoy the power of OasCore!
+
+For more information and advanced usage, visit the [OasCore GitHub repository](https://github.com/a-chacon/oas_core).
+
+      "
+      end
+    end
+  end
+end

data/lib/oas_core/spec/license.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OasCore
+  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
+        %i[name url]
+      end
+    end
+  end
+end

data/lib/oas_core/spec/media_type.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Spec
+    class MediaType
+      include Specable
+
+      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(specification)
+        @specification = specification
+        @schema = {}
+        @example =  {}
+        @examples = {}
+      end
+
+      def oas_fields
+        %i[schema example examples encoding]
+      end
+    end
+  end
+end

data/lib/oas_core/spec/operation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OasCore
+  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
+        %i[tags summary description operation_id parameters request_body responses security]
+      end
+    end
+  end
+end

data/lib/oas_core/spec/parameter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Spec
+    class Parameter
+      include Specable
+      include Hashable
+
+      STYLE_DEFAULTS = { query: 'form', path: 'simple', header: 'simple', cookie: 'form' }.freeze
+
+      attr_accessor :name, :style, :description, :required, :schema
+      attr_reader :in
+
+      def initialize(specification)
+        @specification = specification
+        @name = ''
+        @in = ''
+        @description = ''
+        @required = false
+        @style = ''
+        @schema = { type: 'string' }
+      end
+
+      def in=(value)
+        @in = value
+        @style = STYLE_DEFAULTS[@in.to_sym]
+        @required = true if value == 'path'
+      end
+
+      def required?
+        @in == 'path'
+      end
+
+      def oas_fields
+        %i[name in description required schema style]
+      end
+    end
+  end
+end

data/lib/oas_core/spec/path_item.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OasCore
+  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 add_operation(http_method, operation)
+        instance_variable_set("@#{http_method}", operation)
+      end
+
+      def oas_fields
+        OasCore.config.http_verbs
+      end
+    end
+  end
+end

data/lib/oas_core/spec/paths.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Spec
+    class Paths
+      include Specable
+
+      attr_accessor :path_items
+
+      def initialize(specification)
+        @specification = specification
+        @path_items = {}
+      end
+
+      def add_path(path, oas_routes)
+        @path_items[path] = Builders::PathItemBuilder.new(@specification).with_oas_routes(oas_routes).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_core/spec/reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OasCore
+  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_core/spec/request_body.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OasCore
+  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
+        %i[description content required]
+      end
+    end
+  end
+end

data/lib/oas_core/spec/response.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OasCore
+  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
+        %i[description content]
+      end
+    end
+  end
+end

data/lib/oas_core/spec/responses.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OasCore
+  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_core/spec/server.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Spec
+    class Server
+      include Specable
+      attr_accessor :url, :description
+
+      def initialize(url:, description:)
+        @url = url
+        @description = description
+      end
+
+      def oas_fields
+        %i[url description]
+      end
+    end
+  end
+end