oas_rage 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 105b36f0df7a0ce3a829ba070e83b30cf6d7bfc512ef45950c11bf62eb8f0760
+  data.tar.gz: 3c01928efdc49854f1b3bc5e65f7404a21a2e4ab8b169cabfada0ba45ca6e5bf
+SHA512:
+  metadata.gz: 88a773990c11d3d748b206c2bd9a188d3962606253d465a8c92ce912e450a79ddbabb729901acc19b5784b45b67558718f1490fd798bd8bdb4401138600482a1
+  data.tar.gz: eac5dc00f10a0c19a7b799d10c310ccddb2ca4a232429a2f6f041765662011c9773fbf06ab93fb5d5fb4c87efe24ff4c71bab327edeb0dd2866db3bb2ce0c24b

data/.release-please-config.json

@@ -0,0 +1,64 @@
+{
+  "release-type": "ruby",
+  "changelog-sections": [
+    {
+      "type": "feat",
+      "section": "Features"
+    },
+    {
+      "type": "feature",
+      "section": "Features"
+    },
+    {
+      "type": "fix",
+      "section": "Bug Fixes"
+    },
+    {
+      "type": "perf",
+      "section": "Performance Improvements"
+    },
+    {
+      "type": "revert",
+      "section": "Reverts"
+    },
+    {
+      "type": "docs",
+      "section": "Documentation"
+    },
+    {
+      "type": "style",
+      "section": "Styles",
+      "hidden": true
+    },
+    {
+      "type": "chore",
+      "section": "Miscellaneous Chores",
+      "hidden": true
+    },
+    {
+      "type": "refactor",
+      "section": "Code Refactoring"
+    },
+    {
+      "type": "test",
+      "section": "Tests"
+    },
+    {
+      "type": "build",
+      "section": "Build System",
+      "hidden": true
+    },
+    {
+      "type": "ci",
+      "section": "Continuous Integration",
+      "hidden": true
+    }
+  ],
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "oas_rage",
+      "version-file": "lib/oas_rage/version.rb"
+    }
+  }
+}

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

data/.rubocop.yml

@@ -0,0 +1,12 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: disable
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 15

data/.rubocop_todo.yml

@@ -0,0 +1,12 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-06-10 00:03:15 UTC using RuboCop version 1.76.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 19

data/.ruby-version

@@ -0,0 +1 @@
+3.4.4

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/a-chacon/oas_rage/compare/oas_rage-v0.1.0...oas_rage/v0.2.0) (2025-06-10)
+
+
+### Features
+
+* first release, minimal features ([406f64f](https://github.com/a-chacon/oas_rage/commit/406f64f634288beb2f99cf466de09de02f607597))

data/README.md

@@ -0,0 +1,38 @@
+![Gem Version](https://img.shields.io/gem/v/oas_rage?color=E9573F)
+![GitHub License](https://img.shields.io/github/license/a-chacon/oas_rage?color=blue)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/a-chacon/oas_rage/.github%2Fworkflows%2Frubyonrails.yml)
+![Gem Total Downloads](https://img.shields.io/gem/dt/oas_rage)
+![Static Badge](https://img.shields.io/badge/Rails-%3E%3D7.0.0-%23E9573F)
+![Static Badge](https://img.shields.io/badge/Ruby-%3E%3D3.1.0-%23E9573F)
+
+# 📃Open API Specification For Rage
+
+OasRage is a tool for generating **automatic interactive documentation for your Rage APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
+
+Built for the high-performance [Rage](https://github.com/rage-rb/rage) framework, OasRage leverages Rage's compatibility with Rails and its modern Ruby features, including fiber scheduling for non-blocking I/O. It relies on the [OasCore](https://github.com/a-chacon/oas_core) gem for seamless OpenAPI integration.
+
+![Screenshot](https://a-chacon.com/assets/images/oas_rage_ui.png)
+
+## Documentation
+
+For details on how to install, configure, and use OasRage, please refer to the [OasCore MDBook](http://a-chacon.com/oas_core).
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star⭐! Thanks again!
+
+If you plan a big feature, first open an issue to discuss it before any development.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.en.html#license-text).
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=a-chacon/oas_rage&type=Date)](https://www.star-history.com/#a-chacon/oas_rails&Date)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/oas_rage/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OasRage
+  class Configuration < OasCore::Configuration
+    attr_accessor :autodiscover_request_body, :autodiscover_responses, :ignored_actions, :rapidoc_theme, :layout
+    attr_reader :route_extractor, :include_mode
+
+    def initialize
+      super
+      @route_extractor = RouteExtractor
+      @include_mode = :all
+      @autodiscover_request_body = true
+      @autodiscover_responses = true
+      @ignored_actions = []
+      @rapidoc_theme = :rails
+      @layout = nil
+
+      # TODO: implement
+      # autodiscover_request_body
+      # autodiscover_responses
+    end
+
+    def include_mode=(value)
+      valid_modes = %i[all with_tags explicit]
+      raise ArgumentError, "include_mode must be one of #{valid_modes}" unless valid_modes.include?(value)
+
+      @include_mode = value
+    end
+  end
+end

data/lib/oas_rage/oas_route_builder.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module OasRage
+  class OasRouteBuilder
+    def self.build_from_rage_route(rage_route)
+      new(rage_route).build
+    end
+
+    def initialize(rage_route)
+      @rage_route = rage_route
+    end
+
+    def build
+      OasCore::OasRoute.new(
+        controller_class: controller_class,
+        controller_action: controller_action,
+        controller: controller,
+        method_name: method,
+        verb: verb,
+        path: path,
+        docstring: docstring,
+        source_string: source_string,
+        tags: tags
+      )
+    end
+
+    private
+
+    def controller_class
+      controller_name = @rage_route[:meta][:raw_handler].split('#').first
+      "#{Utils.camelize(controller_name)}Controller"
+    end
+
+    def controller_action
+      "#{controller_class}##{@rage_route[:meta][:raw_handler].split('#').last}"
+    end
+
+    def controller
+      @rage_route[:meta][:raw_handler].split('#').first
+    end
+
+    def method
+      @rage_route[:meta][:raw_handler].split('#').last
+    end
+
+    def verb
+      @rage_route[:method]
+    end
+
+    def path
+      @rage_route[:path].to_s.gsub('(.:format)', '').gsub(/:\w+/) { |match| "{#{match[1..]}}" }
+    end
+
+    def source_string
+      Utils.constantize(controller_class).instance_method(method).source
+    end
+
+    def docstring
+      comment_lines = Utils.constantize(controller_class).instance_method(method).comment.lines
+      processed_lines = comment_lines.map { |line| line.sub(/^# /, '') }
+      ::YARD::Docstring.parser.parse(processed_lines.join).to_docstring
+    end
+
+    def tags
+      method_comment = Utils.constantize(controller_class).instance_method(method).comment
+      class_comment = Utils.constantize(controller_class).instance_method(method).class_comment
+
+      method_tags = parse_tags(method_comment)
+      class_tags = parse_tags(class_comment)
+
+      method_tags + class_tags
+    end
+
+    def parse_tags(comment)
+      lines = comment.lines.map { |line| line.sub(/^# /, '') }
+      ::YARD::Docstring.parser.parse(lines.join).tags
+    end
+  end
+end

data/lib/oas_rage/route_extractor.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module OasRage
+  class RouteExtractor
+    def initialize
+      @host_routes = nil
+      @host_paths = nil
+    end
+
+    def host_routes_by_path(path)
+      host_routes.select { |r| r.path == path }
+    end
+
+    def host_routes
+      @host_routes ||= extract_host_routes
+    end
+
+    # Clear instance variable @host_routes
+    #
+    # This method clears the instance variable @host_routes
+    # to force a re-extraction of the routes.
+    def clear_cache
+      @host_routes = nil
+      @host_paths = nil
+    end
+
+    def host_paths
+      @host_paths ||= host_routes.map(&:path).uniq.sort
+    end
+
+    private
+
+    def extract_host_routes
+      routes = valid_routes.map { |r| OasRouteBuilder.build_from_rage_route(r) }
+      routes.select! { |route| route.tags.any? } if OasRage.config.include_mode == :with_tags
+      if OasRage.config.include_mode == :explicit
+        routes.select! do |route|
+          route.tags.any? do |t|
+            t.tag_name == 'oas_include'
+          end
+        end
+      end
+      routes
+    end
+
+    def valid_routes
+      Rage.__router.routes.select do |route|
+        valid_api_route?(route)
+      end
+    end
+
+    def valid_api_route?(route)
+      return false unless valid_route_implementation?(route)
+      # return false unless route.path.spec.to_s.start_with?(OasRage.config.api_path)
+      return false if ignore_custom_actions(route)
+
+      true
+    end
+
+    # Checks if a route has a valid implementation.
+    #
+    # This method verifies that both the controller and the action specified
+    # in the route exist. It checks if the controller class is defined and
+    # if the action method is implemented within that controller.
+    #
+    # @param route [ActionDispatch::Journey::Route] The route to check.
+    # @return [Boolean] true if both the controller and action exist, false otherwise.
+    def valid_route_implementation?(route)
+      raw_handler = route[:meta][:raw_handler]
+      return false unless raw_handler.is_a?(String) && raw_handler.include?('#')
+
+      controller_name, action_name = raw_handler.split('#')
+      controller_name = "#{Utils.camelize(controller_name)}Controller"
+
+      controller_class = Utils.safe_constantize(controller_name)
+      return false unless controller_class
+
+      controller_class.instance_methods.include?(action_name.to_sym)
+    end
+
+    # Ignore user-specified paths in initializer configuration.
+    # Sanitize api_path by removing the "/" if it starts with that, and adding "/" if it ends without that.
+    # Support controller name only to ignore all controller actions.
+    # Support ignoring "controller#action"
+    # Ignoring "controller#action" AND "api_path/controller#action"
+    def ignore_custom_actions(route)
+      api_path = "#{OasRage.config.api_path.sub(%r{\A/}, '')}/".sub(%r{/+$}, '/')
+      ignored_actions = OasRage.config.ignored_actions.flat_map do |custom_route|
+        if custom_route.start_with?(api_path)
+          [custom_route]
+        else
+          ["#{api_path}#{custom_route}", custom_route]
+        end
+      end
+
+      raw_handler = route[:meta][:raw_handler]
+      return false unless raw_handler.is_a?(String) && raw_handler.include?('#')
+
+      controller_action = raw_handler
+      controller_only = raw_handler.split('#').first
+
+      ignored_actions.include?(controller_action) || ignored_actions.include?(controller_only)
+    end
+  end
+end

data/lib/oas_rage/utils.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OasRage
+  module Utils
+    def self.camelize(str)
+      str.split('_').map(&:capitalize).join
+    end
+
+    def self.safe_constantize(str)
+      Object.const_get(str)
+    rescue NameError
+      nil
+    end
+
+    def self.constantize(str)
+      Object.const_get(str)
+    end
+  end
+end

data/lib/oas_rage/version.rb

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