rails_routes_to_openapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fded852e3d8520a0ca3e59b04afa46d637185933027c8d960872f29c28c3bc6d
+  data.tar.gz: 8e3e5578b948e57a89a6ae82be630240fa55a7a35efc92a855013297bfa6e244
+SHA512:
+  metadata.gz: f00dfdbe5d465f5069718d5c10f281ce8cdde15afae559101e2739437e3a7b1038f83c56e0b538cdeb18008ea674d2e43e1d6efe904835787a84432e27d662c4
+  data.tar.gz: f86f5e5a6a07647fcb3e7af9315f74595be110e4019791d1591eec865b0434e8de84673780af97e795a67addb60177c966dc56040a9d427e09a6aa5d397f3723

data/README.md

@@ -0,0 +1,83 @@
+# Converting a Rails Routes Output into a Postman Collection
+
+In an effort to learn a little bit about Ruby and Rails, I decided a fun project would be to attempt generating a YAML file that aligns with the OpenAPI v3.1.0 specification. This file can then be imported into Postman so you can test Rails routes without manually using the Rails console or the consuming frontend application.
+
+## Quick Start
+
+1. Add the gem to your Gemfile:
+
+```ruby
+gem 'rails_routes_to_openapi'
+```
+
+2. Install dependencies:
+
+```shell
+bundle install
+```
+
+3. Run the conversion task:
+
+```shell
+bundle exec rake routes_to_openapi:convert
+```
+
+This task will internally run `rails routes` on your Rails application and generate an OpenAPI YAML file named similar to `openapi_v3.1_YYYYMMDDHHMMSS.yml` in the project root.
+
+> [!WARNING] > **Tip:** Ensure you run the task within a Rails project context so that it can properly pull the routes.
+
+## Workflow Overview
+
+1. **Routes Processing**  
+   The conversion workflow starts by reading the output of `rails routes`, splitting it into lines, and filtering out header information. A helper module parses each line into a structured `RouteInfo` object that captures the HTTP verb, URI pattern, and the associated controller action.
+
+2. **OpenAPI Generation**  
+   The parsed routes are then converted into an OpenAPI compliant hash. The conversion process does the following:
+
+   - It adapts URL parameters (e.g., turning `/a/b/:param/d` into `/a/b/{param}`).
+   - For non-GET verbs, it attaches a default request body schema.
+   - Finally, it merges the above details into an OpenAPI compliant hash which is then dumped into YAML format.
+
+3. **Output**  
+   The generated YAML file contains:
+   - OpenAPI version information.
+   - Descriptive metadata (title, description, version, etc.).
+   - A list of servers.
+   - A paths list that maps each route to its HTTP verb and summary (derived from the controller action).
+
+## Example OpenAPI YAML Output
+
+Below is an abbreviated snippet of what the output might look like:
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Rails Routes to OpenAPI
+  description: Generate an OpenAPI v3.1 YAML file for Postman import
+  version: "1.1.0"
+servers:
+  - url: "https://api.example.com"
+    description: "Base URL for the API"
+paths:
+  "/":
+    get:
+      summary: "home#show"
+  "/path/to/authorize/native":
+    get:
+      summary: "doorkeeper/authorizations#show"
+  "/path/to/authorize":
+    get:
+      summary: "doorkeeper/authorizations#new"
+    delete:
+      summary: "doorkeeper/authorizations#destroy"
+      requestBody:
+        required: true
+        content:
+          "application/json":
+            schema:
+              type: object
+              properties:
+                id:
+                  type: string
+                  format: string
+```

data/Rakefile

@@ -0,0 +1,23 @@
+require "rake"
+require_relative "lib/rails_routes_to_openapi"
+
+namespace :routes_to_openapi do
+  desc "Convert Rails routes to OpenAPI YAML"
+  task :convert do
+    routes_output = IO.popen("rails routes") { |io| io.read }
+
+    # Check if the output contains expected routes information
+    if routes_output.include?("Usage:") || routes_output.strip.empty?
+      puts "Failed to retrieve routes. Please ensure you are running this task within a Rails project."
+      exit 1
+    end
+
+    begin
+      RailsRoutesToOpenAPI.convert(routes_output)
+      puts 'OpenAPI v3 YAML file generated successfully.'
+    rescue => e
+      puts "Failed to generate OpenAPI YAML file."
+      puts e.message
+    end
+  end
+end

data/lib/rails_routes_to_openapi/structs/open_api.rb

@@ -0,0 +1,46 @@
+require "dry-struct"
+require_relative "../types/index"
+
+module Structs
+  module OpenAPI
+    class Base < Dry::Struct
+      attribute :openapi, Types::String
+      attribute :info, Types::Hash.schema(
+        title: Types::Strict::String,
+        description: Types::Strict::String,
+        version: Types::String
+      )
+      attribute :servers, Types::Array.of(
+        Types::Hash.schema(
+          url: Types::Strict::String,
+          description: Types::Strict::String
+        )
+      )
+      attribute :paths, Types::Strict::Hash
+    end
+
+    class VerbWithRequestBody < Dry::Struct
+      attribute :summary, Types::Strict::String
+      attribute :requestBody, Types::Hash.schema(
+        required: Types::Strict::Bool,
+        content: Types::Hash.schema(
+          "application/json": Types::Hash.schema(
+            schema: Types::Hash.schema(
+              type: Types::Strict::String,
+              properties: Types::Hash.schema(
+                id: Types::Hash.schema(
+                  type: Types::Strict::String,
+                  format: Types::Strict::String
+                )
+              )
+            )
+          )
+        )
+      )
+    end
+
+    class Verb < Dry::Struct
+      attribute :summary, Types::Strict::String
+    end
+  end
+end

data/lib/rails_routes_to_openapi/structs/rails_route_info.rb

@@ -0,0 +1,12 @@
+require "dry-struct"
+require_relative "../types/index"
+
+module Structs
+  class RouteInfo < Dry::Struct
+    attribute :verb, Types::Strict::String
+    attribute :uri_pattern, Types::Strict::String
+    attribute :controller_action, Types::Strict::String
+
+    attr_writer :uri_pattern
+  end
+end

data/lib/rails_routes_to_openapi/types/index.rb

@@ -0,0 +1,3 @@
+module Types
+  include Dry.Types()
+end

data/lib/rails_routes_to_openapi/util/file_helpers.rb

@@ -0,0 +1,46 @@
+require_relative "../structs/rails_route_info"
+module Util
+  class FileHelpers
+    class << self
+      # Takes routes output and returns RouteInfo based on each line
+      # for REST verb, uri_pattern and associated controller_action
+      def parse(routes_output)
+        split_file_data = split(routes_output)
+        filtered_file_data = filter_header(split_file_data)
+        create_route_info(filtered_file_data)
+      end
+
+      # Returns string array for each line
+      def split(file_content)
+        file_content.split(/\n/)
+      rescue
+        raise "Failed to split file content"
+      end
+
+      # Filter out the header line
+      def filter_header(file_content_array)
+        # Assuming the first line is the header
+        file_content_array.drop(1)
+      rescue
+        raise "Failed to filter header"
+      end
+
+      # Accepts string array from file line
+      def create_route_info(file_data)
+        # Use regex to split each line into prefix, verb, uri_pattern, and controller_action
+        file_data.flat_map { |line|
+          next if line.empty?
+          match = line.match(/^\s*(\S*)\s*(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)?\s+(\S+)\s+(.+)\s*$/)
+          if match
+            prefix, verb, uri_pattern, controller_action = match.captures
+            # Split the verb by '|' if it exists, otherwise default to 'GET'
+            verbs = verb&.split('|') || ['GET']
+            verbs.map { |v| Structs::RouteInfo.new(verb: v, uri_pattern: uri_pattern, controller_action: controller_action) }
+          end
+        }.compact
+      rescue
+        raise "Failed to map line to RouteInfo"
+      end
+    end
+  end
+end

data/lib/rails_routes_to_openapi/util/open_api_helpers.rb

@@ -0,0 +1,76 @@
+require "deep_merge"
+require_relative "../structs/open_api"
+
+module Util
+  class OpenAPIHelpers
+    class << self
+      # Takes an array of RouteInfo types and generates the OpenAPI v3 spec
+      # to write into YAML and export to a file.
+      def convert(route_info)
+        param_friendly_route_info = convert_params_to_compatible_format(route_info)
+        paths_hash = write_paths_hash(param_friendly_route_info)
+        write_open_api_compliant_hash(paths_hash)
+      end
+
+      def convert_params_to_compatible_format(route_info)
+        route_info.map { |info|
+          # Remove (.:format) from uri_pattern
+          update_string = info.uri_pattern.gsub(/\(\.:format\)/, '')
+          
+          # Turn something like /a/b/:param/d to /a/b/{param} for OpenAPI standards
+          update_string = update_string.split("/").map { |uri|
+            uri[0] == ":" ? "{#{uri[1..]}}" : uri
+          }.join("/")
+
+          Structs::RouteInfo.new(verb: info.verb, controller_action: info.controller_action, uri_pattern: update_string)
+        }
+      rescue
+        raise 'Could not convert params from :param to {param} format'
+      end
+
+      # ! To be honest, I feel like all of this should be cleaned up.
+      # Even if it is just that I need a better formatter to make it read easier.
+      # I feel like the following four methods are a bit wtf really.
+      def get_request_body_schema
+        {type: "object", properties: {id: {type: "string", format: "string"}}}
+      end
+
+      def get_verb_with_req_body(info)
+        Structs::OpenAPI::VerbWithRequestBody.new(summary: info.controller_action, requestBody: {required: true, content: {"application/json": {schema: get_request_body_schema}}}).attributes
+      end
+
+      def get_verb(info)
+        Structs::OpenAPI::Verb.new(summary: info.controller_action).attributes
+      end
+
+      def write_paths_hash(route_info)
+        paths_hash = {}
+        route_info.each do |info|
+          # Simplify the GET part - assume all other REST verbs require a request body
+          if info.verb == "GET"
+            paths_hash.deep_merge!({info.uri_pattern => {info.verb.downcase => get_verb(info)}})
+          else
+            paths_hash.deep_merge!({info.uri_pattern => {info.verb.downcase => get_verb_with_req_body(info)}})
+          end
+        end
+        paths_hash
+      rescue
+        raise 'Could not write paths for hash'
+      end
+
+      def write_open_api_compliant_hash(paths_hash)
+        info = {
+          title: "Rails Routes to OpenAPI",
+          description: "Generate an OpenAPI v3.1 YAML file for Postman import",
+          version: "1.1.0",
+        }
+        servers = [{url: "https://api.example.com", description: "Base URL for the API"}]
+
+        # This ends up the final hash to write to disk.
+        Structs::OpenAPI::Base.new(openapi: "3.1.0", info: info, servers: servers, paths: paths_hash).attributes
+      rescue
+        raise 'Could not write OpenAPI compliant hash'
+      end
+    end
+  end
+end

data/lib/rails_routes_to_openapi.rb

@@ -0,0 +1,34 @@
+require "yaml"
+require_relative "rails_routes_to_openapi/util/file_helpers"
+require_relative "rails_routes_to_openapi/util/open_api_helpers"
+
+module RailsRoutesToOpenAPI
+  class ::Hash
+    def deep_stringify_keys
+      each_with_object({}) do |(k, v), h|
+        h[k.to_s] = case v
+                    when Hash
+                      v.deep_stringify_keys
+                    when Array
+                      v.map { |i| i.is_a?(Hash) ? i.deep_stringify_keys : i }
+                    else
+                      v
+                    end
+      end
+    end
+  end
+
+  def self.convert(routes_output)
+    route_info = Util::FileHelpers.parse(routes_output)
+    yaml_format = Util::OpenAPIHelpers.convert(route_info).to_hash.deep_stringify_keys.to_yaml
+    timestamp = Time.now.strftime("%Y%m%d%H%M%S")
+    output_file = "openapi_v3.1_#{timestamp}.yml"
+
+    File.open(output_file, "w") { |file| file.write(yaml_format) }
+  end
+end
+
+# Load Rake tasks if Rails is defined
+if defined?(Rails)
+  Dir[File.join(__dir__, 'tasks/**/*.rake')].each { |ext| load ext }
+end

data/lib/tasks/routes_to_openapi.rake

@@ -0,0 +1,23 @@
+require "rake"
+require_relative "../rails_routes_to_openapi"
+
+namespace :routes_to_openapi do
+  desc "Convert Rails routes to OpenAPI YAML"
+  task :convert do
+    routes_output = IO.popen("rails routes") { |io| io.read }
+
+    # Check if the output contains expected routes information
+    if routes_output.include?("Usage:") || routes_output.strip.empty?
+      puts "Failed to retrieve routes. Please ensure you are running this task within a Rails project."
+      exit 1
+    end
+
+    begin
+      RailsRoutesToOpenAPI.convert(routes_output)
+      puts 'OpenAPI v3 YAML file generated successfully.'
+    rescue => e
+      puts "Failed to generate OpenAPI YAML file."
+      puts e.message
+    end
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: rails_routes_to_openapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Camel Chang
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-02-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: deep_merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A gem to convert Rails routes to OpenAPI YAML for Postman import
+email:
+- a556622821@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/rails_routes_to_openapi.rb
+- lib/rails_routes_to_openapi/structs/open_api.rb
+- lib/rails_routes_to_openapi/structs/rails_route_info.rb
+- lib/rails_routes_to_openapi/types/index.rb
+- lib/rails_routes_to_openapi/util/file_helpers.rb
+- lib/rails_routes_to_openapi/util/open_api_helpers.rb
+- lib/tasks/routes_to_openapi.rake
+homepage: https://github.com/camel2243/rails-gen-openapi
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Convert Rails routes to OpenAPI YAML
+test_files: []