grape-path-helpers 1.0.0

data/lib/grape-path-helpers.rb

@@ -0,0 +1,16 @@
+require 'grape'
+require 'active_support'
+require 'active_support/core_ext/class'
+
+require 'grape-path-helpers/decorated_route'
+require 'grape-path-helpers/named_route_matcher'
+require 'grape-path-helpers/all_routes'
+require 'grape-path-helpers/route_displayer'
+
+# Load the Grape route helper for Rails
+module GrapePathHelpers
+  require 'grape-path-helpers/railtie' if defined?(Rails)
+end
+
+Grape::API.extend GrapePathHelpers::AllRoutes
+Grape::Endpoint.send(:include, GrapePathHelpers::NamedRouteMatcher)

data/lib/grape-path-helpers/all_routes.rb

@@ -0,0 +1,18 @@
+module GrapePathHelpers
+  # methods to extend Grape::API's behavior so it can get a
+  # list of routes from all APIs and decorate them with
+  # the DecoratedRoute class
+  module AllRoutes
+    def decorated_routes
+      # memoize so that construction of decorated routes happens once
+      @decorated_routes ||= all_routes
+                            .map { |r| DecoratedRoute.new(r) }
+                            .sort_by { |r| -r.dynamic_path_segments.count }
+    end
+
+    def all_routes
+      routes = subclasses.flat_map { |s| s.send(:prepare_routes) }
+      routes.uniq { |r| r.options.merge(path: r.path) }
+    end
+  end
+end

data/lib/grape-path-helpers/decorated_route.rb

@@ -0,0 +1,168 @@
+module GrapePathHelpers
+  # wrapper around Grape::Route that adds a helper method
+  class DecoratedRoute
+    attr_reader :route, :helper_names, :helper_arguments,
+                :extension, :route_options
+
+    def self.sanitize_method_name(string)
+      string.gsub(/\W|^[0-9]/, '_')
+    end
+
+    def initialize(route)
+      @route = route
+      @route_options = route.options
+      @helper_names = []
+      @helper_arguments = required_helper_segments
+      @extension = default_extension
+      define_path_helpers
+    end
+
+    def default_extension
+      pattern = /\((\.\:?\w+)\)$/
+      match = route_path.match(pattern)
+      return '' unless match
+      ext = match.captures.first
+      if ext == '.:format'
+        ''
+      else
+        ext
+      end
+    end
+
+    def define_path_helpers
+      route_versions.each do |version|
+        route_attributes = { version: version, format: extension }
+        method_name = path_helper_name(route_attributes)
+        @helper_names << method_name
+        define_path_helper(method_name, route_attributes)
+      end
+    end
+
+    def define_path_helper(method_name, route_attributes)
+      method_body = <<-RUBY
+        def #{method_name}(attributes = {})
+          attrs = #{route_attributes}.merge(attributes)
+
+          query_params = attrs.delete(:params)
+          content_type = attrs.delete(:format)
+          path = '/' + path_segments_with_values(attrs).join('/')
+
+          path + content_type + query_string(query_params)
+        end
+      RUBY
+      instance_eval method_body
+    end
+
+    def query_string(params)
+      if params.nil?
+        ''
+      else
+        '?' + params.to_param
+      end
+    end
+
+    def route_versions
+      if route_version.is_a?(Array)
+        route_version
+      elsif route_version
+        version_pattern = /[^\[",\]\s]+/
+        route_version.scan(version_pattern)
+      else
+        [nil]
+      end
+    end
+
+    def path_helper_name(opts = {})
+      if route_options[:as]
+        name = route_options[:as].to_s
+      else
+        segments = path_segments_with_values(opts)
+
+        name = if segments.empty?
+                 'root'
+               else
+                 segments.join('_')
+               end
+      end
+
+      sanitized_name = self.class.sanitize_method_name(name)
+      sanitized_name + '_path'
+    end
+
+    def segment_to_value(segment, opts = {})
+      if dynamic_segment?(segment)
+        options = route.options.merge(stringify_keys(opts))
+        key = segment.slice(1..-1).to_sym
+        options[key]
+      else
+        segment
+      end
+    end
+
+    def path_segments_with_values(opts)
+      segments = path_segments.map { |s| segment_to_value(s, opts) }
+      segments.reject(&:blank?)
+    end
+
+    def path_segments
+      pattern = %r{\(/?\.:?\w+\)|/|\??\*}
+      route_path.split(pattern).reject(&:blank?)
+    end
+
+    def dynamic_path_segments
+      segments = path_segments.select do |segment|
+        dynamic_segment?(segment)
+      end
+      segments.map { |s| s.slice(1..-1) }
+    end
+
+    def dynamic_segment?(segment)
+      segment.start_with?(':')
+    end
+
+    def required_helper_segments
+      segments_in_options = dynamic_path_segments.select do |segment|
+        route.options[segment.to_sym]
+      end
+      dynamic_path_segments - segments_in_options
+    end
+
+    def special_keys
+      %w[format params]
+    end
+
+    def uses_segments_in_path_helper?(segments)
+      segments = segments.reject { |x| special_keys.include?(x) }
+
+      if required_helper_segments.empty? && segments.any?
+        false
+      else
+        required_helper_segments.all? { |x| segments.include?(x) }
+      end
+    end
+
+    def route_path
+      route.path
+    end
+
+    def route_version
+      route.version
+    end
+
+    def route_namespace
+      route.namespace
+    end
+
+    def route_method
+      route.request_method
+    end
+
+    private
+
+    def stringify_keys(original)
+      original.each_with_object({}) do |(key, value), hash|
+        hash[key.to_sym] = value
+      end
+    end
+  end
+end

data/lib/grape-path-helpers/named_route_matcher.rb

@@ -0,0 +1,36 @@
+module GrapePathHelpers
+  # methods to extend Grape::Endpoint so that calls
+  # to unknown methods will look for a route with a matching
+  # helper function name
+  module NamedRouteMatcher
+    def method_missing(method_id, *arguments)
+      super unless method_id.to_s =~ /_path$/
+      segments = arguments.first || {}
+
+      route = Grape::API.decorated_routes.detect do |r|
+        route_match?(r, method_id, segments)
+      end
+
+      if route
+        route.send(method_id, *arguments)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, _include_private = false)
+      Grape::API.decorated_routes.detect do |r|
+        route_match?(r, method_name, {})
+      end
+    end
+
+    def route_match?(route, method_name, segments)
+      return false unless route.respond_to?(method_name)
+      # rubocop:disable Metrics/LineLength
+      raise ArgumentError, 'Helper options must be a hash' unless segments.is_a?(Hash)
+      # rubocop:enable Metrics/LineLength
+      requested_segments = segments.keys.map(&:to_s)
+      route.uses_segments_in_path_helper?(requested_segments)
+    end
+  end
+end

data/lib/grape-path-helpers/railtie.rb

@@ -0,0 +1,9 @@
+module GrapePathHelpers
+  # Pulls in Rake helper for displaying route helper methods
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      files = File.join(File.dirname(__FILE__), '../tasks/*.rake')
+      Dir[files].each { |f| load f }
+    end
+  end
+end

data/lib/grape-path-helpers/route_displayer.rb

@@ -0,0 +1,31 @@
+module GrapePathHelpers
+  # class for displaying the path, helper method name,
+  # and required arguments for every Grape::Route.
+  class RouteDisplayer
+    def route_attributes
+      Grape::API.decorated_routes.map do |route|
+        {
+          route_path: route.route_path,
+          route_method: route.route_method,
+          helper_names: route.helper_names,
+          helper_arguments: route.helper_arguments
+        }
+      end
+    end
+
+    def display
+      puts("== GRAPE ROUTE HELPERS ==\n\n")
+      route_attributes.each do |attributes|
+        printf("%s: %s\n", 'Verb', attributes[:route_method])
+        printf("%s: %s\n", 'Path', attributes[:route_path])
+        printf("%s: %s\n",
+               'Helper Method',
+               attributes[:helper_names].join(', '))
+        printf("%s: %s\n",
+               'Arguments',
+               attributes[:helper_arguments].join(', '))
+        puts("\n")
+      end
+    end
+  end
+end

data/lib/grape-path-helpers/tasks.rb

@@ -0,0 +1 @@
+Dir[File.join(File.dirname(__FILE__), '../tasks/*.rake')].each { |f| load f }

data/lib/grape-path-helpers/version.rb

@@ -0,0 +1,4 @@
+# Gem version
+module GrapePathHelpers
+  VERSION = '1.0.0'.freeze
+end

data/lib/grape/path_helpers.rb

@@ -0,0 +1 @@
+require 'grape-path-helpers'

data/lib/tasks/grape_path_helpers.rake

@@ -0,0 +1,6 @@
+namespace :grape do
+  desc 'Print route helper methods.'
+  task route_helpers: :environment do
+    GrapePathHelpers::RouteDisplayer.new.display
+  end
+end

data/spec/grape_path_helpers/all_routes_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe GrapePathHelpers::AllRoutes do
+  Grape::API.extend described_class
+
+  describe '#all_routes' do
+    context 'when API is mounted within another API' do
+      let(:mounting_api) { Spec::Support::MountedAPI }
+
+      it 'does not include the same route twice' do
+        mounting_api
+
+        # A route is unique if no other route shares the same set of options
+        all_route_options = Grape::API.all_routes.map do |r|
+          r.instance_variable_get(:@options).merge(path: r.path)
+        end
+
+        duplicates = all_route_options.select do |o|
+          all_route_options.count(o) > 1
+        end
+
+        expect(duplicates).to be_empty
+      end
+    end
+
+    # rubocop:disable Metrics/LineLength
+    context 'when there are multiple POST routes with the same namespace in the same API' do
+      it 'returns all POST routes' do
+        expected_routes = Spec::Support::MultiplePostsAPI.routes.map(&:path)
+
+        all_routes = Grape::API.all_routes
+        expect(all_routes.map(&:path)).to include(*expected_routes)
+      end
+    end
+    # rubocop:enable Metrics/LineLength
+  end
+end

data/spec/grape_path_helpers/decorated_route_spec.rb

@@ -0,0 +1,241 @@
+require 'spec_helper'
+
+# rubocop:disable Metrics/BlockLength
+describe GrapePathHelpers::DecoratedRoute do
+  let(:api) { Spec::Support::API }
+
+  let(:routes) do
+    api.routes.map do |route|
+      described_class.new(route)
+    end
+  end
+
+  let(:index_route) do
+    routes.detect { |route| route.route_namespace == '/cats' }
+  end
+
+  let(:show_route) do
+    routes.detect { |route| route.route_namespace == '/cats/:id' }
+  end
+
+  let(:catch_all_route) do
+    routes.detect { |route| route.route_path =~ /\*/ }
+  end
+
+  let(:custom_route) do
+    routes.detect { |route| route.route_path =~ /custom_name/ }
+  end
+
+  let(:ping_route) do
+    routes.detect { |route| route.route_path =~ /ping/ }
+  end
+
+  describe '#sanitize_method_name' do
+    it 'removes characters that are illegal in Ruby method names' do
+      illegal_names = ['beta-1', 'name_with_+', 'name_with_(']
+      sanitized = illegal_names.map do |name|
+        described_class.sanitize_method_name(name)
+      end
+      expect(sanitized).to match_array(%w[beta_1 name_with__ name_with__])
+    end
+
+    it 'only replaces integers if they appear at the beginning' do
+      illegal_name = '1'
+      legal_name = 'v1'
+      expect(described_class.sanitize_method_name(illegal_name)).to eq('_')
+      expect(described_class.sanitize_method_name(legal_name)).to eq('v1')
+    end
+  end
+
+  describe '#helper_names' do
+    context 'when a route is given a custom helper name' do
+      it 'uses the custom name instead of the dynamically generated one' do
+        expect(custom_route.helper_names.first)
+          .to eq('my_custom_route_name_path')
+      end
+
+      it 'returns the correct path' do
+        expect(
+          custom_route.my_custom_route_name_path
+        ).to eq('/api/v1/custom_name.json')
+      end
+    end
+
+    context 'when an API has multiple POST routes in a resource' do
+      let(:api) { Spec::Support::MultiplePostsAPI }
+
+      it 'it creates a helper for each POST route' do
+        expect(routes.size).to eq(2)
+      end
+    end
+
+    context 'when an API has multiple versions' do
+      let(:api) { Spec::Support::APIWithMultipleVersions }
+
+      it "returns the route's helper name for each version" do
+        helper_names = ping_route.helper_names
+        expect(helper_names.size).to eq(api.versions.size)
+      end
+
+      it 'returns an array of the routes versions' do
+        expect(ping_route.route_version).to eq(%w[beta alpha v1])
+      end
+    end
+
+    context 'when an API has one version' do
+      it "returns the route's helper name for that version" do
+        helper_name = show_route.helper_names.first
+        expect(helper_name).to eq('api_v1_cats_path')
+      end
+    end
+  end
+
+  describe '#helper_arguments' do
+    context 'when no user input is needed to generate the correct path' do
+      it 'returns an empty array' do
+        expect(index_route.helper_arguments).to eq([])
+      end
+    end
+
+    context 'when user input is needed to generate the correct path' do
+      it 'returns an array of required segments' do
+        expect(show_route.helper_arguments).to eq(['id'])
+      end
+    end
+  end
+
+  describe '#path_segments_with_values' do
+    context 'when path has dynamic segments' do
+      it 'replaces segments with corresponding values found in @options' do
+        opts = { id: 1 }
+        result = show_route.path_segments_with_values(opts)
+        expect(result).to include(1)
+      end
+
+      context 'when options contains string keys' do
+        it 'replaces segments with corresponding values found in the options' do
+          opts = { 'id' => 1 }
+          result = show_route.path_segments_with_values(opts)
+          expect(result).to include(1)
+        end
+      end
+    end
+  end
+
+  describe '#path_helper_name' do
+    it "returns the name of a route's helper method" do
+      expect(index_route.path_helper_name).to eq('api_v1_cats_path')
+    end
+
+    context 'when the path is the root path' do
+      let(:api_with_root) do
+        Class.new(Grape::API) do
+          get '/' do
+          end
+        end
+      end
+
+      let(:root_route) do
+        grape_route = api_with_root.routes.first
+        described_class.new(grape_route)
+      end
+
+      it 'returns "root_path"' do
+        result = root_route.path_helper_name
+        expect(result).to eq('root_path')
+      end
+    end
+
+    context 'when the path is a catch-all path' do
+      it 'returns a name without the glob star' do
+        result = catch_all_route.path_helper_name
+        expect(result).to eq('api_v1_path_path')
+      end
+    end
+  end
+
+  describe '#segment_to_value' do
+    context 'when segment is dynamic' do
+      it 'returns the value the segment corresponds to' do
+        result = index_route.segment_to_value(':version')
+        expect(result).to eq('v1')
+      end
+
+      context 'when segment is found in options' do
+        it 'returns the value found in options' do
+          options = { id: 1 }
+          result = show_route.segment_to_value(':id', options)
+          expect(result).to eq(1)
+        end
+      end
+    end
+
+    context 'when segment is static' do
+      it 'returns the segment' do
+        result = index_route.segment_to_value('api')
+        expect(result).to eq('api')
+      end
+    end
+  end
+
+  describe 'path helper method' do
+    context 'when given a "params" key' do
+      context 'when value under "params" key is a hash' do
+        it 'creates a query string' do
+          query = { foo: :bar, baz: :zot }
+          path = index_route.api_v1_cats_path(params: query)
+          expect(path).to eq('/api/v1/cats.json?' + query.to_param)
+        end
+      end
+
+      context 'when value under "params" is not a hash' do
+        it 'coerces the value into a string' do
+          path = index_route.api_v1_cats_path(params: 1)
+          expect(path).to eq('/api/v1/cats.json?1')
+        end
+      end
+    end
+
+    # handle different Grape::Route#route_path formats in Grape 0.12.0
+    context 'when route_path contains a specific format' do
+      it 'returns the correct path with the correct format' do
+        path = index_route.api_v1_cats_path
+        expect(path).to eq('/api/v1/cats.json')
+      end
+    end
+
+    context 'when helper does not require arguments' do
+      it 'returns the correct path' do
+        path = index_route.api_v1_cats_path
+        expect(path).to eq('/api/v1/cats.json')
+      end
+    end
+
+    context 'when arguments are needed required to construct the right path' do
+      context 'when not missing arguments' do
+        it 'returns the correct path' do
+          path = show_route.api_v1_cats_path(id: 1)
+          expect(path).to eq('/api/v1/cats/1.json')
+        end
+      end
+    end
+
+    context "when a route's API has multiple versions" do
+      let(:api) { Spec::Support::APIWithMultipleVersions }
+
+      it 'returns a path for each version' do
+        expect(ping_route.alpha_ping_path).to eq('/alpha/ping')
+        expect(ping_route.beta_ping_path).to eq('/beta/ping')
+        expect(ping_route.v1_ping_path).to eq('/v1/ping')
+      end
+    end
+
+    context 'when a format is given' do
+      it 'returns the path with a correct extension' do
+        path = show_route.api_v1_cats_path(id: 1, format: '.xml')
+        expect(path).to eq('/api/v1/cats/1.xml')
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength