oas_rails 0.1.0

data/lib/oas_rails/oas_route.rb

@@ -0,0 +1,143 @@
+module OasRails
+  class OasRoute
+    attr_accessor(:controller_class, :controller_action, :controller, :controller_path, :method, :verb, :path,
+                  :rails_route, :docstring, :source_string)
+
+    def initialize; end
+
+    def self.new_from_rails_route(rails_route: ActionDispatch::Journey::Route)
+      instance = new
+      instance.rails_route = rails_route
+      instance.extract_rails_route_data
+      instance
+    end
+
+    def extract_rails_route_data
+      @controller_action = "#{@rails_route.defaults[:controller].camelize}Controller##{@rails_route.defaults[:action]}"
+      @controller_class = "#{@rails_route.defaults[:controller].camelize}Controller"
+      @controller = @rails_route.defaults[:controller]
+      @controller_path = controller_path_extractor(@rails_route.defaults[:controller])
+      @method = @rails_route.defaults[:action]
+      @verb = @rails_route.verb
+      @path = RouteExtractor.clean_route(@rails_route.path.spec.to_s)
+      @docstring = extract_docstring
+      @source_string = extract_source_string
+    end
+
+    def extract_docstring
+      YARD::Docstring.parser.parse(
+        controller_class.constantize.instance_method(method).comment.lines.map { |line| line.sub(/^#\s*/, '') }.join
+      ).to_docstring
+    end
+
+    def extract_source_string
+      @controller_class.constantize.instance_method(method).source
+    end
+
+    def path_params
+      @rails_route.path.spec.to_s.scan(/:(\w+)/).flatten.reject! { |e| e == 'format' }
+    end
+
+    def controller_path_extractor(controller)
+      Rails.root.join("app/controllers/#{controller}_controller.rb").to_s
+    end
+
+    def detect_request_body
+      klass = @controller.singularize.camelize.constantize
+      RequestBody.from_model_class(klass:, required: true)
+    end
+
+    def extract_responses_from_source
+      render_calls = @source_string.scan(/render json: ((?:\{.*?\}|\S+))(?:, status: :(\w+))?(?:,.*?)?$/m)
+
+      return [Response.new(code: 204, description: "No Content", content: {})] if render_calls.empty?
+
+      render_calls.map do |render_content, status|
+        content = render_content.strip
+
+        # TODO: manage when is an array of errors
+        schema = {}
+        begin
+          schema = if content.start_with?('{')
+                     OasRails.hash_to_json_schema(parse_hash_structure(content))
+                   else
+                     # It's likely a variable or method call
+                     maybe_a_model, errors = content.gsub('@', "").split(".")
+                     klass = maybe_a_model.singularize.camelize(:upper).constantize
+                     return {} unless klass.ancestors.include? ActiveRecord::Base
+
+                     e = Esquema::Builder.new(klass).build_schema.as_json
+                     if test_singularity(maybe_a_model)
+                       if errors.nil?
+                         e
+                       else
+                         {
+                           type: "object",
+                           properties: {
+                             success: {
+                               type: "boolean"
+                             },
+                             errors: {
+                               type: "object",
+                               additionalProperties: {
+                                 type: "array",
+                                 items: {
+                                   type: "string"
+                                 }
+                               }
+                             }
+                           }
+                         } end
+                     else
+                       { type: "array", items: e }
+                     end
+                   end
+        rescue StandardError => e
+          Rails.logger.debug("Error building schema: #{e.message}")
+        end
+
+        status_int = status_to_integer(status)
+        Response.new(code: status_int, description: status_code_to_text(status_int), content: { "application/json": MediaType.new(schema:) })
+      end
+    end
+
+    def test_singularity(str)
+      str.pluralize != str && str.singularize == str
+    end
+
+    def parse_hash_structure(hash_literal)
+      structure = {}
+
+      hash_literal.scan(/(\w+):\s*(\S+)/) do |key, value|
+        structure[key.to_sym] = case value
+                                when 'true', 'false'
+                                  'Boolean'
+                                when /^\d+$/
+                                  'Number'
+                                when '@user.errors'
+                                  'Object'
+                                else
+                                  'Object'
+                                end
+      end
+
+      structure
+    end
+
+    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
+
+    def status_code_to_text(status_code)
+      Rack::Utils::HTTP_STATUS_CODES[status_code] || "Unknown Status Code"
+    end
+  end
+end

data/lib/oas_rails/operation.rb

@@ -0,0 +1,118 @@
+module OasRails
+  class Operation < OasBase
+    attr_accessor :tags, :summary, :description, :operation_id, :parameters, :method, :docstring, :request_body, :responses
+
+    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] || {}
+    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:)
+        new(method: oas_route.verb.downcase, summary:, operation_id:, tags:, description:, parameters:, request_body:, responses:)
+      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.request_body_automatically
+          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 external_docs; end
+    end
+  end
+end

data/lib/oas_rails/parameter.rb

@@ -0,0 +1,47 @@
+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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,87 @@
+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
+
+      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 if route.defaults[:controller].nil?
+        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) }
+
+        true
+      end
+    end
+  end
+end

data/lib/oas_rails/server.rb

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,42 @@
+require 'json'
+
+module OasRails
+  class Specification
+    def initialize
+      OasRails.configure_esquema!
+      OasRails.configure_yard!
+      @specification = base_spec
+    end
+
+    def to_json(*_args)
+      @specification.to_json
+    rescue StandardError => e
+      Rails.logger.error("Error Generating OAS: #{e.message}")
+      {}
+    end
+
+    def base_spec
+      {
+        openapi: '3.1.0',
+        info: OasRails.config.info.to_spec,
+        servers: OasRails.config.servers.map(&:to_spec),
+        paths: paths_spec,
+        components: components_spec,
+        security: [],
+        tags: OasRails.config.tags.map(&:to_spec),
+        externalDocs: {}
+      }
+    end
+
+    def paths_spec
+      Paths.from_string_paths(string_paths: RouteExtractor.host_paths).to_spec
+    end
+
+    def components_spec
+      {
+        schemas: {}, parameters: {}, securitySchemas: {}, requestBodies: {}, responses: {},
+        headers: {}, examples: {}, links: {}, callbacks: {}
+      }
+    end
+  end
+end

data/lib/oas_rails/tag.rb

@@ -0,0 +1,17 @@
+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

data/lib/oas_rails/version.rb

@@ -0,0 +1,3 @@
+module OasRails
+  VERSION = "0.1.0"
+end