oas_rails 0.3.0 → 0.4.0

data/lib/oas_rails/utils.rb

@@ -13,6 +13,14 @@ module OasRails
       'DateTime' => 'string'
     }.freeze
 
+    HTTP_STATUS_DEFINITIONS = {
+      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
       # Method for detect test framework of the Rails App
       # It is used for generate examples in operations
@@ -61,6 +69,37 @@ module OasRails
       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 = "unprocessable_content" if status == "unprocessable_entity"
+          Rack::Utils::SYMBOL_TO_STATUS_CODE[status.to_sym]
+        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 status_code_to_text(status_code)
+        Rack::Utils::HTTP_STATUS_CODES[status_code] || "Unknown Status Code"
+      end
+
+      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_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/oas_rails.rb

@@ -6,27 +6,44 @@ module OasRails
   require "oas_rails/version"
   require "oas_rails/engine"
 
-  autoload :OasBase, "oas_rails/oas_base"
   autoload :Configuration, "oas_rails/configuration"
-  autoload :Specification, "oas_rails/specification"
   autoload :OasRoute, "oas_rails/oas_route"
-  autoload :Operation, "oas_rails/operation"
-  autoload :Info, "oas_rails/info"
-  autoload :Contact, "oas_rails/contact"
-  autoload :Paths, "oas_rails/paths"
-  autoload :PathItem, "oas_rails/path_item"
-  autoload :Parameter, "oas_rails/parameter"
-  autoload :Tag, "oas_rails/tag"
-  autoload :License, "oas_rails/license"
-  autoload :Server, "oas_rails/server"
-  autoload :RequestBody, "oas_rails/request_body"
-  autoload :MediaType, "oas_rails/media_type"
-  autoload :Response, "oas_rails/response"
-  autoload :Responses, "oas_rails/responses"
-
   autoload :Utils, "oas_rails/utils"
   autoload :EsquemaBuilder, "oas_rails/esquema_builder"
 
+  module Builders
+    autoload :OperationBuilder, "oas_rails/builders/operation_builder"
+    autoload :PathItemBuilder, "oas_rails/builders/path_item_builder"
+    autoload :ResponseBuilder, "oas_rails/builders/response_builder"
+    autoload :ResponsesBuilder, "oas_rails/builders/responses_builder"
+    autoload :ContentBuilder, "oas_rails/builders/content_builder"
+    autoload :ParametersBuilder, "oas_rails/builders/parameters_builder"
+    autoload :ParameterBuilder, "oas_rails/builders/parameter_builder"
+    autoload :RequestBodyBuilder, "oas_rails/builders/request_body_builder"
+  end
+
+  # This module contains all the clases that represent a part of the OAS file.
+  module Spec
+    autoload :Hashable, "oas_rails/spec/hashable"
+    autoload :Specable, "oas_rails/spec/specable"
+    autoload :Components, "oas_rails/spec/components"
+    autoload :Parameter, "oas_rails/spec/parameter"
+    autoload :License, "oas_rails/spec/license"
+    autoload :Response, "oas_rails/spec/response"
+    autoload :PathItem, "oas_rails/spec/path_item"
+    autoload :Operation, "oas_rails/spec/operation"
+    autoload :RequestBody, "oas_rails/spec/request_body"
+    autoload :Responses, "oas_rails/spec/responses"
+    autoload :MediaType, "oas_rails/spec/media_type"
+    autoload :Paths, "oas_rails/spec/paths"
+    autoload :Contact, "oas_rails/spec/contact"
+    autoload :Info, "oas_rails/spec/info"
+    autoload :Server, "oas_rails/spec/server"
+    autoload :Tag, "oas_rails/spec/tag"
+    autoload :Specification, "oas_rails/spec/specification"
+    autoload :Reference, "oas_rails/spec/reference"
+  end
+
   module YARD
     autoload :OasYARDFactory, 'oas_rails/yard/oas_yard_factory'
   end
@@ -34,9 +51,17 @@ module OasRails
   module Extractors
     autoload :RenderResponseExtractor, 'oas_rails/extractors/render_response_extractor'
     autoload :RouteExtractor, "oas_rails/extractors/route_extractor"
+    autoload :OasRouteExtractor, "oas_rails/extractors/oas_route_extractor"
   end
 
   class << self
+    def build
+      oas = Spec::Specification.new
+      oas.build
+
+      oas.to_spec
+    end
+
     # Configurations for make the OasRails engine Work.
     def configure
       OasRails.configure_yard!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oas_rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - a-chacon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-08-02 00:00:00.000000000 Z
+date: 2024-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: esquema
@@ -100,27 +100,39 @@ files:
 - lib/generators/oas_rails/config/config_generator.rb
 - lib/generators/oas_rails/config/templates/oas_rails_initializer.rb
 - lib/oas_rails.rb
+- lib/oas_rails/builders/content_builder.rb
+- lib/oas_rails/builders/operation_builder.rb
+- lib/oas_rails/builders/parameter_builder.rb
+- lib/oas_rails/builders/parameters_builder.rb
+- lib/oas_rails/builders/path_item_builder.rb
+- lib/oas_rails/builders/request_body_builder.rb
+- lib/oas_rails/builders/response_builder.rb
+- lib/oas_rails/builders/responses_builder.rb
 - lib/oas_rails/configuration.rb
-- lib/oas_rails/contact.rb
 - lib/oas_rails/engine.rb
 - lib/oas_rails/esquema_builder.rb
+- lib/oas_rails/extractors/oas_route_extractor.rb
 - lib/oas_rails/extractors/render_response_extractor.rb
 - lib/oas_rails/extractors/route_extractor.rb
-- lib/oas_rails/info.rb
-- lib/oas_rails/license.rb
-- lib/oas_rails/media_type.rb
-- lib/oas_rails/oas_base.rb
 - lib/oas_rails/oas_route.rb
-- lib/oas_rails/operation.rb
-- lib/oas_rails/parameter.rb
-- lib/oas_rails/path_item.rb
-- lib/oas_rails/paths.rb
-- lib/oas_rails/request_body.rb
-- lib/oas_rails/response.rb
-- lib/oas_rails/responses.rb
-- lib/oas_rails/server.rb
-- lib/oas_rails/specification.rb
-- lib/oas_rails/tag.rb
+- lib/oas_rails/spec/components.rb
+- lib/oas_rails/spec/contact.rb
+- lib/oas_rails/spec/hashable.rb
+- lib/oas_rails/spec/info.rb
+- lib/oas_rails/spec/license.rb
+- lib/oas_rails/spec/media_type.rb
+- lib/oas_rails/spec/operation.rb
+- lib/oas_rails/spec/parameter.rb
+- lib/oas_rails/spec/path_item.rb
+- lib/oas_rails/spec/paths.rb
+- lib/oas_rails/spec/reference.rb
+- lib/oas_rails/spec/request_body.rb
+- lib/oas_rails/spec/response.rb
+- lib/oas_rails/spec/responses.rb
+- lib/oas_rails/spec/server.rb
+- lib/oas_rails/spec/specable.rb
+- lib/oas_rails/spec/specification.rb
+- lib/oas_rails/spec/tag.rb
 - lib/oas_rails/utils.rb
 - lib/oas_rails/version.rb
 - lib/oas_rails/yard/oas_yard_factory.rb

data/lib/oas_rails/contact.rb

@@ -1,12 +0,0 @@
-module OasRails
-  class Contact < OasBase
-    attr_accessor :name, :url, :email
-
-    def initialize(**kwargs)
-      super()
-      @name = kwargs[:name] || ''
-      @url = kwargs[:url] || ''
-      @email = kwargs[:email] || ''
-    end
-  end
-end

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,102 +0,0 @@
-module OasRails
-  class MediaType < OasBase
-    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(schema:, **kwargs)
-      super()
-      @schema = schema
-      @example = kwargs[:example] || {}
-      @examples = kwargs[:examples] || {}
-    end
-
-    class << self
-      @context = :incoming
-      # Creates a new MediaType object from a model class.
-      #
-      # @param klass [Class] the ActiveRecord model class.
-      # @param examples [Hash] the examples hash.
-      # @return [MediaType, nil] the created MediaType object or nil if the class is not an ActiveRecord model.
-      def from_model_class(klass:, context: :incoming, examples: {})
-        @context = context
-        return unless klass.ancestors.include? ActiveRecord::Base
-
-        model_schema = EsquemaBuilder.send("build_#{@context}_schema", klass:)
-        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.
-      #
-      # @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
-
-      # Transforms tags into examples.
-      #
-      # @param tags [Array] the array of tags.
-      # @return [Hash] the transformed examples hash.
-      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
-
-      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 = klass.to_s.downcase.to_sym
-        begin
-          FactoryBot.build_stubbed_list(klass_sym, 3).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

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 = Extractors::RenderResponseExtractor.extract_responses_from_source(source: oas_route.source_string)
-
-          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: Extractors::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/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