apipie-rails 1.1.0 → 1.2.0

data/Gemfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec path: '.'
+
+# use ENV vars, with default value as fallback for local setup
+ruby(ENV['RUBY_VERSION'] || '3.2.2')
+gem 'actionpack', "~> #{ENV['RAILS_VERSION'] || '7.0'}.0"
+gem 'activesupport', "~> #{ENV['RAILS_VERSION'] || '7.0'}.0"
+
+gem 'mime-types' # , '~> 3.0'
+gem 'rails-controller-testing'
+gem 'rspec-rails' # , '~> 5.0'
+
+# net-smtp not included by default in Ruby 3.1
+# Will be fixed by https://github.com/mikel/mail/pull/1439
+gem 'net-smtp', require: false if Gem.ruby_version >= Gem::Version.new('3.1.0')
+
+gem 'test_engine', path: './spec/dummy/components/test_engine', group: :test

data/README.rst

@@ -108,6 +108,10 @@ resource_id
 name
   Human readable name of resource. By default ``class.name.humanize`` is used.
 
+  - Can be specified as a proc, which will receive the controller class as an argument.
+  - Can be a symbol, which will be sent to the controller class to get the name.
+  - Can be a string, which will be used as is.
+
 short (also short_description)
   Short description of the resource (it's shown on both the list of resources, and resource details)
 
@@ -1180,7 +1184,7 @@ Here is an example of how to rescue and process a +ParamMissing+ or
 +ParamInvalid+ error from within the ApplicationController.
 
 .. code:: ruby
-  
+
   class ApplicationController < ActionController::Base
 
     # ParamError is superclass of ParamMissing, ParamInvalid
@@ -1925,14 +1929,10 @@ And if you write one on your own, don't hesitate to share it with us!
  Contributing
 ====================
 
-Since this gem does not have a Gemfile, you need to specify it in your shell with:
-
-.. code:: shell
-   BUNDLE_GEMFILE='gemfiles/Gemfile.rails61'
-
 Then, you can install dependencies and run the test suite:
 
 .. code:: shell
+
    > bundle install
    > bundle exec rspec
 

data/app/controllers/apipie/apipies_controller.rb

@@ -154,26 +154,12 @@ module Apipie
 
     def render_from_cache
       path = Apipie.configuration.doc_base_url.dup
-      # some params can contain dot, but only one in row
-      if [:resource, :method, :format, :version].any? { |p| params[p].to_s.gsub(".", "") =~ /\W/ || params[p].to_s.include?('..') }
-        head :bad_request and return
-      end
-
       path << "/" << params[:version] if params[:version].present?
       path << "/" << params[:resource] if params[:resource].present?
       path << "/" << params[:method] if params[:method].present?
-      if params[:format].present?
-        path << ".#{params[:format]}"
-      else
-        path << ".html"
-      end
-
-      # we sanitize the params before so in ideal case, this condition
-      # will be never satisfied. It's here for cases somebody adds new
-      # param into the path later and forgets about sanitation.
-      if path.include?('..')
-        head :bad_request and return
-      end
+      # Sanitize path against directory traversal attacks (e.g. ../../foo)
+      # by turning path into an absolute path before appending it to the cache dir
+      path = File.expand_path("#{path}.#{request.format.symbol}", '/')
 
       cache_file = File.join(Apipie.configuration.cache_dir, path)
       if File.exist?(cache_file)

data/gemfiles/Gemfile.tools

@@ -0,0 +1,9 @@
+# This Gemfile is used for IDEs like VS Code that need specific gems installed
+# for their tools to work properly. It is not used for the application itself.
+
+source 'https://rubygems.org'
+
+gem 'rubocop-rails'
+gem 'rubocop-rspec'
+gem 'rubocop-performance'
+gem 'ruby-lsp', '~> 0.5.1'

data/lib/apipie/application.rb

@@ -122,15 +122,26 @@ module Apipie
     # resource_description? It's used to derivate the default value of
     # versions for methods.
     def controller_versions(controller)
-      ret = @controller_versions[controller.to_s]
-      return ret unless ret.empty?
-      if controller == ActionController::Base || controller.nil?
-        return [Apipie.configuration.default_version]
-      else
-        return controller_versions(controller.to_s.constantize.superclass)
+      value_from_parents(controller, default: [Apipie.configuration.default_version]) do |c|
+        ret = @controller_versions[c.to_s]
+        ret unless ret.empty?
       end
     end
 
+    # Recursively walks up the controller hierarchy looking for a value
+    # from the block.
+    # Stops at ActionController::Base.
+    # @param [Class] controller controller to start from
+    # @param [Array] args arguments passed to the block
+    # @param [Object] default default value to return if no value is found
+    # @param [Proc] block block to call with controller and args
+    def value_from_parents(controller, *args, default: nil, &block)
+      return default if controller == ActionController::Base || controller == AbstractController::Base || controller.nil?
+
+      thing = yield(controller, *args)
+      thing || value_from_parents(controller.superclass, *args, default: default, &block)
+    end
+
     def set_controller_versions(controller, versions)
       @controller_versions[controller.to_s] = versions
     end
@@ -443,7 +454,7 @@ module Apipie
     end
 
     def version_prefix(klass)
-      version = controller_versions(klass.to_s).first
+      version = controller_versions(klass).first
       base_url = get_base_url(version)
       return "/" if base_url.blank?
       base_url[1..-1] + "/"

data/lib/apipie/dsl_definition.rb

@@ -259,7 +259,7 @@ module Apipie
               if Apipie.configuration.validate_key?
                 params.reject{|k,_| %w[format controller action].include?(k.to_s) }.each_pair do |param, _|
                   # params allowed
-                  if method_params.select {|_,p| p.name.to_s == param.to_s}.empty?
+                  if method_params.none? {|_,p| p.name.to_s == param.to_s}
                     self.class._apipie_handle_validate_key_error params, param
                   end
                 end

data/lib/apipie/extractor/collector.rb

@@ -19,7 +19,7 @@ module Apipie
       def ignore_call?(record)
         return true unless record[:controller]
         return true if @ignored.include?(record[:controller].name)
-        return true if @ignored.include?("#{Apipie.resource_id(record[:controller].name)}##{record[:action]}")
+        return true if @ignored.include?("#{Apipie.get_resource_id(record[:controller].name)}##{record[:action]}")
         return true unless @api_controllers_paths.include?(controller_full_path(record[:controller]))
       end
 

data/lib/apipie/extractor/recorder.rb

@@ -48,7 +48,7 @@ module Apipie
         else
           @query = request.query_string
         end
-        if response.content_type != 'application/pdf'
+        if response.media_type != 'application/pdf'
           @response_data = parse_data(response.body)
         end
         @code = response.code

data/lib/apipie/generator/swagger/warning.rb

@@ -59,7 +59,7 @@ class Apipie::Generator::Swagger::Warning
   #
   # @return [Apipie::Generator::Swagger::Warning]
   def self.for_code(code, method_id, message_attributes = {})
-    if !CODES.values.include?(code)
+    if !CODES.value?(code)
       raise ArgumentError, 'Unknown warning code'
     end
 

data/lib/apipie/resource_description.rb

@@ -26,7 +26,9 @@ module Apipie
       @controller = controller
       @_id = id
       @_version = version || Apipie.configuration.default_version
-      @_parent = Apipie.get_resource_description(controller.superclass, version)
+      @_parent = Apipie.value_from_parents(controller.superclass, version) do |parent, ver|
+        Apipie.get_resource_description(parent, ver)
+      end
 
       update_from_dsl_data(dsl_data) if dsl_data
     end
@@ -60,7 +62,16 @@ module Apipie
     end
 
     def name
-      @name ||= @_resource_name.presence || @_id.split('-').map(&:capitalize).join('::')
+      @name ||= case resource_name
+                when Proc
+          resource_name.call(controller)
+                when Symbol
+          controller.public_send(resource_name)
+                when String
+          resource_name
+        else
+          default_name
+        end
     end
     alias _name name
 
@@ -90,7 +101,9 @@ module Apipie
       Apipie.full_url crumbs.join('/')
     end
 
-    def api_url; "#{Apipie.api_base_url(_version)}#{@_path}"; end
+    def api_url
+      "#{Apipie.api_base_url(_version)}#{@_path}"
+    end
 
     def valid_method_name?(method_name)
       @_methods.keys.map(&:to_s).include?(method_name.to_s)
@@ -123,5 +136,17 @@ module Apipie
       }
     end
 
+    protected
+
+    def resource_name
+      @_resource_name.presence || @_parent&.resource_name
+    end
+
+    private
+
+    def default_name
+      @_id.split('-').map(&:capitalize).join('::')
+    end
+
   end
 end

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/spec/controllers/api/v2/architectures_controller_spec.rb

@@ -1,12 +1,19 @@
 require 'spec_helper'
 
 describe Api::V2::ArchitecturesController do
+  let(:resource_description) { Apipie.get_resource_description(described_class, "2.0") }
+
   describe "resource description" do
-    subject { Apipie.get_resource_description(Api::V2::ArchitecturesController, "2.0") }
+    describe 'version' do
+      subject { resource_description._version }
 
-    it "should be version 2.0" do
-      expect(subject._version).to eq('2.0')
+      it { is_expected.to eq('2.0') }
     end
 
+    describe 'name' do
+      subject { resource_description.name }
+
+      it { is_expected.to eq('Architectures') }
+    end
   end
 end

data/spec/controllers/api/v2/empty_middle_controller_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe Api::V2::EmptyMiddleController do
+  let(:resource_description) { Apipie.get_resource_description(described_class, '2.0') }
+
+  describe 'resource description' do
+    subject { resource_description }
+
+    context 'when namespaced resources are enabled' do
+      before { Apipie.configuration.namespaced_resources = true }
+      after { Apipie.configuration.namespaced_resources = false }
+
+      # we don't actually expect the resource description to be nil, but resource IDs
+      # are computed at file load time, and altering the value of namespaced_resources
+      # after the fact doesn't change the resource ID, so it can't be found
+      it { is_expected.to be_nil }
+    end
+
+    context 'when namespaced resources are disabled' do
+      it { is_expected.to be_nil }
+    end
+  end
+end

data/spec/controllers/api/v2/nested/resources_controller_spec.rb

@@ -1,6 +1,22 @@
 require 'spec_helper'
 
 describe Api::V2::Nested::ResourcesController do
+  let(:resource_description) { Apipie.get_resource_description(described_class, "2.0") }
+
+  describe "resource description" do
+    describe 'version' do
+      subject { resource_description._version }
+
+      it { is_expected.to eq('2.0') }
+    end
+
+    describe 'name' do
+      subject { resource_description.name }
+
+      it { is_expected.to eq('Rsrcs') }
+    end
+  end
+
   describe '.get_resource_id' do
     subject { Apipie.get_resource_id(Api::V2::Nested::ResourcesController) }
 

data/spec/controllers/api/v2/sub/footguns_controller_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe Api::V2::Sub::FootgunsController do
+  let(:resource_description) { Apipie.get_resource_description(described_class, '2.0') }
+
+  describe 'resource description' do
+    describe 'version' do
+      subject { resource_description._version }
+
+      it { is_expected.to eq('2.0') }
+    end
+
+    describe 'name' do
+      subject { resource_description.name }
+
+      it { is_expected.to eq('snugtooF') }
+    end
+  end
+end

data/spec/dummy/app/controllers/api/v2/base_controller.rb

@@ -5,6 +5,12 @@ module Api
         api_version '2.0'
         app_info 'Version 2.0 description'
         api_base_url '/api/v2'
+
+        name :reversed_name
+      end
+
+      def self.reversed_name
+        controller_name.capitalize.reverse
       end
     end
   end

data/spec/dummy/app/controllers/api/v2/empty_middle_controller.rb

@@ -0,0 +1,14 @@
+module Api
+  module V2
+    class EmptyMiddleController < V2::BaseController
+      # This is an empty controller, used to test cases where controllers
+      # may inherit from a middle controler that does not define a resource_description,
+      # but the middle controller's parent does.
+
+      def inconsequential_method
+        # This method is here to ensure that the controller is not empty.
+        # It triggers method_added, which is used to add the resource description.
+      end
+    end
+  end
+end

data/spec/dummy/app/controllers/api/v2/nested/resources_controller.rb

@@ -1,8 +1,8 @@
 module Api
   module V2
     class Nested::ResourcesController < V2::BaseController
-      resource_description do 
-        name 'Resources'
+      resource_description do
+        name ->(controller) { controller.controller_name.delete('aeiou').capitalize }
         resource_id "resource"
       end
       api :GET, "/nested/resources/", "List all nested resources."

data/spec/dummy/app/controllers/api/v2/sub/footguns_controller.rb

@@ -0,0 +1,30 @@
+module Api
+  module V2
+    module Sub
+      class FootgunsController < V2::EmptyMiddleController
+        resource_description do
+          short 'Footguns are bad'
+        end
+
+        api :GET, '/footguns/', 'List all footguns.'
+        def index; end
+
+        api :GET, '/footguns/:id/', 'Show a footgun.'
+        def show; end
+
+        api :POST, '/footguns/', 'Create a footgun.'
+        def create; end
+
+        api :PUT, '/footguns/:id/', 'Update a footgun.'
+        param :footgun, Hash, :required => true do
+          param :name, String
+        end
+        def update; end
+
+        api! 'Delete a footgun.'
+        api_version '2.0' # forces removal of the method description
+        def destroy; end
+      end
+    end
+  end
+end

data/spec/lib/apipie/apipies_controller_spec.rb

@@ -258,12 +258,12 @@ describe Apipie::ApipiesController, type: :controller do
 
     before do
       FileUtils.rm_r(cache_dir) if File.exist?(cache_dir)
-      FileUtils.mkdir_p(File.join(cache_dir, "apidoc", "v1", "resource"))
+      FileUtils.mkdir_p(File.join(cache_dir, "apidoc", "v1", "resource-with-namespace"))
       File.open(File.join(cache_dir, "apidoc", "v1.html"), "w") { |f| f << "apidoc.html cache v1" }
       File.open(File.join(cache_dir, "apidoc", "v2.html"), "w") { |f| f << "apidoc.html cache v2" }
       File.open(File.join(cache_dir, "apidoc", "v1.json"), "w") { |f| f << "apidoc.json cache" }
-      File.open(File.join(cache_dir, "apidoc", "v1", "resource.html"), "w") { |f| f << "resource.html cache" }
-      File.open(File.join(cache_dir, "apidoc", "v1", "resource", "method.html"), "w") { |f| f << "method.html cache" }
+      File.open(File.join(cache_dir, "apidoc", "v1", "resource-with-namespace.html"), "w") { |f| f << "resource-with-namespace.html cache" }
+      File.open(File.join(cache_dir, "apidoc", "v1", "resource-with-namespace", "method.html"), "w") { |f| f << "method.html cache" }
 
       Apipie.configuration.use_cache = true
       @orig_cache_dir = Apipie.configuration.cache_dir
@@ -279,24 +279,68 @@ describe Apipie::ApipiesController, type: :controller do
       # FileUtils.rm_r(cache_dir) if File.exist?(cache_dir)
     end
 
-    it "uses the file in cache dir instead of generating the content on runtime" do
-      get :index
-      expect(response.body).to eq("apidoc.html cache v1")
-      get :index, :params => { :version => 'v1' }
-      expect(response.body).to eq("apidoc.html cache v1")
-      get :index, :params => { :version => 'v2' }
-      expect(response.body).to eq("apidoc.html cache v2")
-      get :index, :params => { :version => 'v1', :format => "html" }
-      expect(response.body).to eq("apidoc.html cache v1")
-      get :index, :params => { :version => 'v1', :format => "json" }
-      expect(response.body).to eq("apidoc.json cache")
-      get :index, :params => { :version => 'v1', :format => "html", :resource => "resource" }
-      expect(response.body).to eq("resource.html cache")
-      get :index, :params => { :version => 'v1', :format => "html", :resource => "resource", :method => "method" }
-      expect(response.body).to eq("method.html cache")
+    context 'when the file exists' do
+      it "uses the file in cache dir instead of generating the content on runtime" do
+        get :index
+        expect(response.body).to eq("apidoc.html cache v1")
+
+        get :index, :params => { :version => 'v1' }
+        expect(response.body).to eq("apidoc.html cache v1")
+
+        get :index, :params => { :version => 'v2' }
+        expect(response.body).to eq("apidoc.html cache v2")
+
+        get :index, :params => { :version => 'v1', :format => "html" }
+        expect(response.body).to eq("apidoc.html cache v1")
+
+        get :index, :params => { :version => 'v1', :format => "json" }
+        expect(response.body).to eq("apidoc.json cache")
+
+        get :index, :params => { :version => 'v1', :format => "html", :resource => "resource-with-namespace" }
+        expect(response.body).to eq("resource-with-namespace.html cache")
+
+        get :index, :params => { :version => 'v1', :format => "html", :resource => "resource-with-namespace", :method => "method" }
+        expect(response.body).to eq("method.html cache")
+      end
     end
 
-  end
+    context 'when the file does not exist' do
+      it 'returns a not found' do
+        get :index, :params => { :version => 'v3-does-not-exist' }
+        expect(response).to have_http_status(:not_found)
+      end
+    end
+
+    context 'preventing path traversal' do
+      context 'when resource contains ..' do
+        it "returns a not found" do
+          get :index, :params => { :version => 'v1', :format => "html", :resource => "../resource-with-namespace", :method => "method" }
+          expect(response).to have_http_status(:not_found)
+        end
+      end
 
+      context 'when method contains ..' do
+        it "returns a not found" do
+          get :index, :params => { :version => 'v1', :format => "html", :resource => "resource-with-namespace", :method => "../method" }
+          expect(response).to have_http_status(:not_found)
+        end
+      end
+
+      context 'when version contains ..' do
+        it "returns a not found" do
+          get :index, :params => { :version => '../v1', :format => "html", :resource => "resource-with-namespace", :method => "method" }
+          expect(response).to have_http_status(:not_found)
+        end
+      end
+
+      context 'when format contains ..' do
+        it "returns a not found" do
+          get :index, :params => { :version => 'v1', :format => "../html", :resource => "resource-with-namespace", :method => "method" }
+          expect(response).to have_http_status(:not_found)
+        end
+      end
+    end
+
+  end
 
 end

data/spec/lib/apipie/extractor/collector_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Apipie::Extractor::Collector do
+  let(:recorder) { described_class.new }
+
+  describe '#ignore_call?' do
+    subject { recorder.ignore_call?(record) }
+
+    let(:record) { { controller: controller, action: action } }
+    let(:controller) { ActionController::Base }
+    let(:action) { nil }
+
+    context 'when controller is nil' do
+      let(:controller) { nil }
+
+      it { is_expected.to be true }
+    end
+
+    context 'when controller is ignored' do
+      before do
+        allow(Apipie.configuration).to receive(:ignored_by_recorder).and_return(['ActionController::Bas'])
+      end
+
+      it { is_expected.to be true }
+    end
+
+    context 'when resource#method is ignored' do
+      let(:action) { 'ignored_action' }
+
+      before do
+        allow(Apipie.configuration).to receive(:ignored_by_recorder).and_return(['ActionController::Bas#ignored_action'])
+      end
+
+      it { is_expected.to be true }
+    end
+
+    context 'when controller is not an API controller' do
+      before do
+        allow(Apipie::Extractor).to receive(:controller_path).with('action_controller/base').and_return('foo')
+        allow(Apipie).to receive(:api_controllers_paths).and_return([])
+      end
+
+      it { is_expected.to be true }
+    end
+
+    context 'when controller is an API controller' do
+      before do
+        allow(Apipie::Extractor).to receive(:controller_path).with('action_controller/base').and_return('foo')
+        allow(Apipie).to receive(:api_controllers_paths).and_return(['foo'])
+      end
+
+      it { is_expected.to be_falsey }
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apipie-rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Pavel Pokorny
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-16 00:00:00.000000000 Z
+date: 2023-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -208,8 +208,10 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- ".vscode/settings.json"
 - APACHE-LICENSE-2.0
 - CHANGELOG.md
+- Gemfile
 - MIT-LICENSE
 - NOTICE
 - PROPOSAL_FOR_RESPONSE_DESCRIPTIONS.md
@@ -258,12 +260,7 @@ files:
 - config/locales/tr.yml
 - config/locales/zh-CN.yml
 - config/locales/zh-TW.yml
-- gemfiles/Gemfile.rails50
-- gemfiles/Gemfile.rails51
-- gemfiles/Gemfile.rails52
-- gemfiles/Gemfile.rails60
-- gemfiles/Gemfile.rails61
-- gemfiles/Gemfile.rails70
+- gemfiles/Gemfile.tools
 - images/screenshot-1.png
 - images/screenshot-2.png
 - lib/apipie-rails.rb
@@ -342,7 +339,9 @@ files:
 - rel-eng/tito.props
 - spec/controllers/api/v1/architectures_controller_spec.rb
 - spec/controllers/api/v2/architectures_controller_spec.rb
+- spec/controllers/api/v2/empty_middle_controller_spec.rb
 - spec/controllers/api/v2/nested/resources_controller_spec.rb
+- spec/controllers/api/v2/sub/footguns_controller_spec.rb
 - spec/controllers/concerns_controller_spec.rb
 - spec/controllers/extended_controller_spec.rb
 - spec/controllers/included_param_group_controller_spec.rb
@@ -354,8 +353,10 @@ files:
 - spec/dummy/app/controllers/api/v1/base_controller.rb
 - spec/dummy/app/controllers/api/v2/architectures_controller.rb
 - spec/dummy/app/controllers/api/v2/base_controller.rb
+- spec/dummy/app/controllers/api/v2/empty_middle_controller.rb
 - spec/dummy/app/controllers/api/v2/nested/architectures_controller.rb
 - spec/dummy/app/controllers/api/v2/nested/resources_controller.rb
+- spec/dummy/app/controllers/api/v2/sub/footguns_controller.rb
 - spec/dummy/app/controllers/application_controller.rb
 - spec/dummy/app/controllers/concerns_controller.rb
 - spec/dummy/app/controllers/extended_controller.rb
@@ -408,6 +409,7 @@ files:
 - spec/lib/apipie/apipies_controller_spec.rb
 - spec/lib/apipie/application_spec.rb
 - spec/lib/apipie/configuration_spec.rb
+- spec/lib/apipie/extractor/collector_spec.rb
 - spec/lib/apipie/extractor/recorder/middleware_spec.rb
 - spec/lib/apipie/extractor/recorder_spec.rb
 - spec/lib/apipie/extractor/writer_spec.rb
@@ -470,7 +472,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.11
 signing_key:
 specification_version: 4
 summary: Rails REST API documentation tool

data/gemfiles/Gemfile.rails50

@@ -1,10 +0,0 @@
-source "https://rubygems.org"
-
-gemspec path: '..'
-
-gem 'actionpack', '~> 5.0.0'
-gem 'activesupport', '~> 5.0.0'
-gem 'mime-types', '~> 2.99.3'
-gem 'rails-controller-testing'
-
-gem 'test_engine', path: '../spec/dummy/components/test_engine', group: :test