oas_rails 0.1.0

data/lib/oas_rails/yard/oas_yard_factory.rb

@@ -0,0 +1,160 @@
+module OasRails
+  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
+
+    class RequestBodyExampleTag < ::YARD::Tags::Tag
+      attr_accessor :content
+
+      def initialize(tag_name, text, content: {})
+        super(tag_name, text, nil, nil)
+        @content = content
+      end
+    end
+
+    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
+
+    class ResponseTag < ::YARD::Tags::Tag
+      attr_accessor :schema
+
+      def initialize(tag_name, name, text, schema)
+        super(tag_name, text, nil, name)
+        @schema = schema
+      end
+    end
+
+    class OasYardFactory < ::YARD::Tags::DefaultFactory
+      ## parse_tag is a prefix used by YARD
+
+      def parse_tag_with_request_body(tag_name, text)
+        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
+        if !match.nil?
+          text = match[1].strip
+          type, required = parse_type(match[2].strip)
+
+          if type.constantize == Hash
+            hash_string = match[3].strip
+
+            begin
+              hash = eval(hash_string)
+              hash = OasRails.hash_to_json_schema(hash)
+            rescue StandardError
+              hash = {}
+            end
+          end
+
+          RequestBodyTag.new(tag_name, text, type.constantize, schema: hash, required:)
+        else
+          Rails.logger.debug("Error parsing request_body tag: #{text}")
+        end
+      end
+
+      def parse_tag_with_request_body_example(tag_name, text)
+        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
+        if !match.nil?
+          text = match[1].strip
+          type = match[2]
+
+          if type.constantize == Hash
+            hash_string = match[3].strip
+
+            begin
+              hash = eval(hash_string)
+            rescue StandardError
+              hash = {}
+            end
+          end
+          RequestBodyExampleTag.new(tag_name, text, content: hash)
+        else
+          Rails.logger.debug("Error parsing request body example tag: #{text}")
+        end
+      end
+
+      def parse_tag_with_parameter(tag_name, text)
+        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
+        if !match.nil?
+          text = match[1].strip
+          name, location = parse_position_name(text)
+          type, required = parse_type(match[2].strip)
+          schema = OasRails.type_to_schema(type)
+
+          ParameterTag.new(tag_name, name, match[3].strip, schema, location, required:)
+        else
+          Rails.logger.debug("Error parsing request body example tag: #{text}")
+        end
+      end
+
+      def parse_tag_with_response(tag_name, text)
+        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
+        if !match.nil?
+          name, code = parse_position_name(match[1].strip)
+
+          begin
+            hash = parse_str_to_hash(match[3].strip)
+            hash = OasRails.hash_to_json_schema(hash)
+          rescue StandardError
+            hash = {}
+          end
+
+          ResponseTag.new(tag_name, code, name, hash)
+        else
+          Rails.logger.debug("Error parsing request body example tag: #{text}")
+        end
+      end
+
+      def parse_position_name(input)
+        return unless input =~ /^([^(]+)\((.*)\)$/
+
+        name = ::Regexp.last_match(1)
+        location = ::Regexp.last_match(2)
+        [name, location]
+      end
+
+      def parse_type(type_string)
+        if type_string.end_with?('!')
+          [type_string.chomp('!'), true]
+        else
+          [type_string, false]
+        end
+      end
+
+      def parse_str_to_hash(str)
+        str = str.gsub(/^\{|\}$/, '') # Remove leading { and trailing }
+        pairs = str.split(',').map(&:strip)
+
+        pairs.each_with_object({}) do |pair, hash|
+          key, value = pair.split(':').map(&:strip)
+          key = key.to_sym
+          hash[key] = case value
+                      when 'String' then String
+                      when 'Integer' then Integer
+                      when 'Float' then Float
+                      when 'Boolean' then [TrueClass, FalseClass]
+                      when 'Array' then Array
+                      when 'Hash' then Hash
+                      when 'DateTime' then DateTime
+                      else value
+                      end
+        end
+      end
+    end
+  end
+end

data/lib/oas_rails.rb

@@ -0,0 +1,120 @@
+require "yard"
+require "method_source"
+require "esquema"
+
+require_relative 'oas_rails/version'
+require_relative 'oas_rails/engine'
+require_relative 'oas_rails/oas_base'
+require_relative 'oas_rails/configuration'
+require_relative 'oas_rails/specification'
+require_relative 'oas_rails/route_extractor'
+require_relative 'oas_rails/oas_route'
+require_relative 'oas_rails/operation'
+
+require_relative 'oas_rails/info'
+require_relative 'oas_rails/contact'
+require_relative 'oas_rails/paths'
+require_relative 'oas_rails/path_item'
+require_relative 'oas_rails/parameter'
+require_relative 'oas_rails/tag'
+require_relative 'oas_rails/license'
+require_relative 'oas_rails/server'
+require_relative "oas_rails/request_body"
+require_relative "oas_rails/media_type"
+require_relative 'oas_rails/yard/oas_yard_factory'
+require_relative "oas_rails/response"
+require_relative "oas_rails/responses"
+
+module OasRails
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure_yard!
+      ::YARD::Tags::Library.default_factory = Yard::OasYardFactory
+      yard_tags = {
+        'Request body' => [:request_body, :with_request_body],
+        'Request body Example' => [:request_body_example, :with_request_body_example],
+        'Parameter' => [:parameter, :with_parameter],
+        'Response' => [:response, :with_response],
+        'Endpoint Tags' => [:tags],
+        'Summary' => [:summary]
+      }
+      yard_tags.each do |tag_name, (method_name, handler)|
+        ::YARD::Tags::Library.define_tag(tag_name, method_name, handler)
+      end
+    end
+
+    def configure_esquema!
+      Esquema.configure do |config|
+        config.exclude_associations = true
+        config.exclude_foreign_keys = true
+        config.excluded_columns = %i[id created_at updated_at deleted_at]
+      end
+    end
+
+    def detect_test_framework
+      if defined?(FactoryBot)
+        :factory_bot
+      elsif ActiveRecord::Base.connection.table_exists?('ar_internal_metadata')
+        :fixtures
+      else
+        :unknown
+      end
+    end
+
+    TYPE_MAPPING = {
+      'String' => 'string',
+      'Integer' => 'number',
+      'Float' => 'number',
+      'TrueClass' => 'boolean',
+      'FalseClass' => 'boolean',
+      'Boolean' => 'boolean',
+      'NilClass' => 'null',
+      'Hash' => 'object',
+      'Object' => 'object',
+      'DateTime' => 'string'
+    }.freeze
+
+    def type_to_schema(type_string)
+      if type_string.start_with?('Array<')
+        inner_type = type_string[/Array<(.+)>$/, 1]
+        {
+          "type" => "array",
+          "items" => type_to_schema(inner_type)
+        }
+      else
+        { "type" => TYPE_MAPPING.fetch(type_string, 'string') }
+      end
+    end
+
+    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
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: oas_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- a-chacon
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-07-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: esquema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |2+
+      # Open API Specification For Rails
+
+      OasRails is a Rails engine for generating **automatic interactive documentation for your Rails APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
+
+      ## What Sets OasRails Apart?
+
+      - **Dynamic**: No command required to generate docs
+      - **Simple**: Complement default documentation with a few comments; no need to learn a complex DSL
+      - **Pure Ruby on Rails APIs**: No additional frameworks needed (e.g., Grape, RSpec)
+
+email:
+- andres.ch@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/oas_rails_manifest.js
+- app/assets/stylesheets/oas_rails/application.css
+- app/controllers/oas_rails/application_controller.rb
+- app/controllers/oas_rails/oas_rails_controller.rb
+- app/helpers/oas_rails/application_helper.rb
+- app/helpers/oas_rails/oas_rails_helper.rb
+- app/helpers/oas_rails/test_helper.rb
+- app/jobs/oas_rails/application_job.rb
+- app/mailers/oas_rails/application_mailer.rb
+- app/models/oas_rails/application_record.rb
+- app/views/layouts/oas_rails/application.html.erb
+- app/views/oas_rails/oas_rails/index.html.erb
+- app/views/oas_rails/test/show.html.erb
+- config/routes.rb
+- 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/configuration.rb
+- lib/oas_rails/contact.rb
+- lib/oas_rails/engine.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/route_extractor.rb
+- lib/oas_rails/server.rb
+- lib/oas_rails/specification.rb
+- lib/oas_rails/tag.rb
+- lib/oas_rails/version.rb
+- lib/oas_rails/yard/oas_yard_factory.rb
+homepage: https://github.com/a-chacon/oas_rails
+licenses:
+- GPL-3.0-only
+metadata:
+  homepage_uri: https://github.com/a-chacon/oas_rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.15
+signing_key:
+specification_version: 4
+summary: OasRails is a Rails engine for generating automatic interactive documentation
+  for your Rails APIs. It generates an OAS document and displays it using a nice UI.
+test_files: []
+...