path-level exclusion (#184)

README.md

@@ -184,6 +184,12 @@ RSpec::OpenAPI.example_types = %i[request]
 # :controller and :action always exist. :format is added when routes is configured as such.
 RSpec::OpenAPI.ignored_path_params = %i[controller action format]
 
+# Configure which paths to ignore.
+# You can exclude some specs via `openapi: false`.
+# But, in a complex API usage scenario, you may need to include spec itself, but exclude some private paths.
+# In that case, you can specify the paths to ignore.
+# String or Regexp is acceptable.
+RSpec::OpenAPI.ignored_paths = ["/admin/full/path/", Regexp.new("^/_internal/")]
 ```
 
 ### Can I use rspec-openapi with `$ref` to minimize duplication of schema?

lib/rspec/openapi.rb

@@ -31,6 +31,7 @@ module RSpec::OpenAPI
   @response_headers = []
   @path_records = Hash.new { |h, k| h[k] = [] }
   @ignored_path_params = %i[controller action format]
+  @ignored_paths = []
 
   # This is the configuraion override file name we look for within each path.
   @config_filename = 'rspec_openapi.rb'
@@ -51,6 +52,7 @@ class << self
                   :example_types,
                   :response_headers,
                   :path_records,
+                  :ignored_paths,
                   :ignored_path_params
 
     attr_reader   :config_filename

lib/rspec/openapi/record_builder.rb

@@ -14,6 +14,8 @@ def build(context, example:)
     path, summary, tags, operation_id, required_request_params, raw_path_params, description, security =
       extract_request_attributes(request, example)
 
+    return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| path.match?(ignored_path) }
+
     request_headers, response_headers = extract_headers(request, response)
 
     RSpec::OpenAPI::Record.new(

spec/integration_tests/rails_test.rb

@@ -11,6 +11,7 @@
 RSpec::OpenAPI.request_headers = %w[X-Authorization-Token]
 RSpec::OpenAPI.response_headers = %w[X-Cursor]
 RSpec::OpenAPI.path = File.expand_path("../rails/doc/openapi.#{ENV.fetch('OPENAPI_OUTPUT', nil)}", __dir__)
+RSpec::OpenAPI.ignored_paths = [Regexp.new('/admin/.*$')]
 RSpec::OpenAPI.comment = <<~COMMENT
   This file is auto-generated by rspec-openapi https://github.com/k0kubun/rspec-openapi
 
@@ -255,3 +256,18 @@ class AdditionalPropertiesTest < ActionDispatch::IntegrationTest
     assert_response 200
   end
 end
+
+class NamespaceTest < ActionDispatch::IntegrationTest
+  i_suck_and_my_tests_are_order_dependent!
+  openapi!
+
+  test 'returns some content' do
+    get '/admin/masters/extensions'
+    assert_response 200
+  end
+
+  test 'creates a content' do
+    post '/admin/masters/extensions'
+    assert_response 200
+  end
+end

spec/integration_tests/roda_test.rb

@@ -10,6 +10,7 @@
 
 RSpec::OpenAPI.title = 'OpenAPI Documentation'
 RSpec::OpenAPI.path = File.expand_path("../roda/doc/openapi.#{ENV.fetch('OPENAPI_OUTPUT', nil)}", __dir__)
+RSpec::OpenAPI.ignored_paths = ['/admin/masters/extensions']
 
 class RodaTest < Minitest::Test
   include Rack::Test::Methods

spec/rails/app/controllers/masters/extensions_controller.rb

@@ -0,0 +1,9 @@
+class Masters::ExtensionsController < ApplicationController
+  def index
+    render json: [{ name: 'my-ext-1' }]
+  end
+
+  def create
+    render json: { message: 'created' }
+  end
+end

spec/rails/config/routes.rb

@@ -22,5 +22,11 @@
     get '/secret_items' => 'secret_items#index'
 
     get '/additional_properties' => 'additional_properties#index'
+
+    scope :admin do
+      namespace :masters do
+        resources :extensions, only: [:index, :create]
+      end
+    end
   end
 end

spec/requests/rails_spec.rb

@@ -11,6 +11,7 @@
 RSpec::OpenAPI.request_headers = %w[X-Authorization-Token Secret-Key]
 RSpec::OpenAPI.response_headers = %w[X-Cursor]
 RSpec::OpenAPI.path = File.expand_path("../rails/doc/openapi.#{ENV.fetch('OPENAPI_OUTPUT', nil)}", __dir__)
+RSpec::OpenAPI.ignored_paths = ['/admin/masters/extensions']
 RSpec::OpenAPI.comment = <<~COMMENT
   This file is auto-generated by rspec-openapi https://github.com/k0kubun/rspec-openapi
 
@@ -255,3 +256,17 @@
     end
   end
 end
+
+RSpec.describe 'Namespace test', type: :request do
+  describe '/admin/masters/extensions' do
+    it 'returns some content' do
+      get '/admin/masters/extensions'
+      expect(response.status).to eq(200)
+    end
+
+    it 'creates a content' do
+      post '/admin/masters/extensions'
+      expect(response.status).to eq(200)
+    end
+  end
+end

spec/requests/roda_spec.rb

@@ -8,6 +8,7 @@
 
 RSpec::OpenAPI.title = 'OpenAPI Documentation'
 RSpec::OpenAPI.path = File.expand_path("../roda/doc/openapi.#{ENV.fetch('OPENAPI_OUTPUT', nil)}", __dir__)
+RSpec::OpenAPI.ignored_paths = ['/admin/masters/extensions']
 
 RSpec::OpenAPI.description_builder = lambda do |example|
   contexts = example.example_group.parent_groups.map(&:description).grep(/\Awhen /)