openapi-ruby 4.0.3 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4bf806084ec440728b07b1cb5105c2e2f8529852b143a087bb919111afd6498
-  data.tar.gz: d73357f612fa69222d354a2f122a496c63bf8d8259ddb15bdfb38c898c7fb335
+  metadata.gz: 5f7b5b27e899e80be2470549b5a347b3e3cd9a3d3974f8d5de3842510741e252
+  data.tar.gz: d322e9f88d6164fe4f6f10203266efa88eb99a6f7b27cf0983376bc3587d2e77
 SHA512:
-  metadata.gz: ea9f2ab82f0cdae01a6a578daa13f7274914a77b2476ba4ff7bbaf4cfd991ea685c608dcd71eac23bb2bc9ebf0ce35d0ac764b63a89bbb35add7e95c73a9d048
-  data.tar.gz: b940f94f696df915e90eccc593ae3901b1bc63229b4158391da62ffddb7fef1932a788358c1bffe771054f3e7d5f68faae36ff549ebb2c1166c078ed8ee58c66
+  metadata.gz: 1a1948211044728807f9ff02fa7a0d81af64c4d52619bbcf43895481d8309e4c949c8e40d8daff4c897d694afc53ac02fd48194fa88203bc49d5d7f102200927
+  data.tar.gz: 55a9e333eff2da6db2a8032ad3777219b8df7957f3fc49b5dafc9fc3f0cf586d35836df8439b3b40dcb09e0c2ed56b7aff6fbe7ebc67b75264bf62c1cede3cc2

data/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">openapi_ruby</h1>
 
 <p align="center">
-  A unified OpenAPI toolkit for Rails that combines test-driven spec generation, reusable schema components as Ruby classes, and runtime request/response validation middleware. Supports OpenAPI 3.0 and 3.1. Works with both RSpec and Minitest.
+  A unified OpenAPI toolkit for Rails, Hanami, and Rack that combines test-driven spec generation, reusable schema components as Ruby classes, and runtime request/response validation middleware. Supports OpenAPI 3.0 and 3.1. Works with both RSpec and Minitest.
 </p>
 
 Replaces [rswag](https://github.com/rswag/rswag), [rswag-schema-components](https://github.com/101skills-gmbh/rswag-schema-components), and [committee](https://github.com/interagent/committee) with a single gem.
@@ -14,6 +14,7 @@ Replaces [rswag](https://github.com/rswag/rswag), [rswag-schema-components](http
 
 - **OpenAPI 3.0 & 3.1** with JSON Schema 2020-12 (via [json_schemer](https://github.com/davishmcclurg/json_schemer))
 - **Test-framework agnostic** — works with RSpec and Minitest
+- **Host-framework agnostic** — works on Rails, Hanami, Sinatra, and bare Rack
 - **Schema components** as Ruby classes with inheritance
 - **Runtime middleware** for request/response validation with deep type checking
 - **Strong params** derived from schema components
@@ -23,7 +24,7 @@ Replaces [rswag](https://github.com/rswag/rswag), [rswag-schema-components](http
 ## Requirements
 
 - Ruby >= 3.2
-- Rails >= 7.0
+- Rails >= 7.0, Hanami >= 2.3, or any Rack app (see [Host Frameworks](#host-frameworks))
 
 ## Installation
 
@@ -47,6 +48,8 @@ This creates:
 - `openapi/` — output directory for generated specs
 - Engine mount in `config/routes.rb`
 
+The install generator is Rails-only — see [Host Frameworks](#host-frameworks) for the equivalent setup elsewhere.
+
 ## Configuration
 
 ```ruby
@@ -497,21 +500,94 @@ require "rails/test_help"
 # ...other test-time setup...
 ```
 
-This is purely an optimization — generation is already correct and database-free without it.
+This is purely an optimization — generation is already correct and database-free without it. Reach for it only if generation is slow enough to bother you.
 
-One caveat if you do guard: skipping `rails/test_help` also means `fixtures` is undefined, so any test file calling `fixtures :all` in its class body fails to *load*. Point `PATTERN` at just the files carrying `api_path` declarations:
+#### When guarding backfires
 
-```bash
-PATTERN="test/integration/api/**/*_test.rb" rake openapi_ruby:generate
+The guard skips a require, so anything that require defines is gone for the whole generation run. That is fine for setup your files only touch while *running*, and fatal for anything they touch while *loading* — a file that fails to load contributes no declarations, and generation fails outright.
+
+Loading a spec/test file executes its class body, so these all break under a guard:
+
+- `fixtures :all` — `fixtures` is undefined without `rails/test_help`
+- `include Devise::Test::IntegrationHelpers` — needs `rspec/rails` (or `rails/test_help`) already loaded
+- `it_behaves_like "..."` / `include_examples` at the top level — needs the shared examples your helper loaded
+
+Two ways out, and they compose:
+
+1. **Narrow `PATTERN`** to just the files carrying `path` / `api_path` declarations, so the files with load-time dependencies are never loaded:
+
+   ```bash
+   PATTERN="test/integration/api/**/*_test.rb" rake openapi_ruby:generate
+   ```
+
+2. **Leave that helper unguarded.** A helper whose constants are referenced at load time across the suite is often not worth guarding — you would be trading a working generation run for a faster one. Guarding is optional per helper; guard `test/test_helper.rb` and leave `spec/rails_helper.rb` alone if that is what your suite needs.
+
+Suites using FactoryBot rather than fixtures, and keeping helper includes inside `before` blocks, tend not to hit any of this.
+
+### How a request finds its api_path (Style 2)
+
+Style 2 separates the `api_path` declaration from the request that exercises
+it, so `assert_api_response` has to match the request back to a declaration. It
+narrows the declared paths by, in order:
+
+1. the verb — only paths declaring it stay in
+2. the path params — a path needing `{project_id}` is out if none was supplied,
+   and a path is out if it doesn't use every key given in `path_params:`
+3. the expected status — `assert_api_response :put, 422` skips paths that don't
+   declare a 422 for that verb
+4. how many supplied keys the path can explain, as either one of its own path
+   params or a parameter declared on the operation
+
+That resolves a collection path against a member path, nested resources, and
+sibling paths distinguished by status. It cannot resolve paths that agree on all
+four:
+
+```ruby
+api_path "/timers/{id}"       { put("Update") { response(200, "ok") } }
+api_path "/timers/{id}/start" { put("Start")  { response(200, "ok") } }
+api_path "/timers/{id}/stop"  { put("Stop")   { response(200, "ok") } }
+```
+
+Nothing at the call site tells those apart, so that raises
+`OpenapiRuby::AmbiguousApiPath` naming the candidates rather than silently
+picking the first and validating against the wrong response schema. Two ways to
+resolve it. Name the path on the request:
+
+```ruby
+assert_api_response :put, 200, path_params: {id: timer.id}, api_path: "/timers/{id}/start"
+```
+
+Or, in RSpec, declare each path in its own example group — a nested `describe`
+only sees paths declared at or above it:
+
+```ruby
+describe "start" do
+  api_path("/timers/{id}/start") { put("Start") { response(200, "ok") } }
+
+  it { assert_api_response :put, 200, path_params: {id: timer.id} }
+end
+
+describe "stop" do
+  api_path("/timers/{id}/stop") { put("Stop") { response(200, "ok") } }
+
+  it { assert_api_response :put, 200, path_params: {id: timer.id} }
+end
+```
+
+To require one path per test class regardless, switch on:
+
+```ruby
+config.single_api_path_per_class = true
 ```
 
-Suites using FactoryBot rather than fixtures don't hit this.
+`api_path` then raises `OpenapiRuby::MultipleApiPaths` as soon as a class
+declares a second path. Off by default.
 
 ### Migrating from RSpec to Minitest (or vice versa)
 
 When both `spec/spec_helper.rb` and `test/test_helper.rb` are present, the rake task auto-selects `FRAMEWORK=hybrid` — it requires both adapters and loads both glob patterns (`spec/**/*_spec.rb,test/**/*_test.rb`) into one process. Style 1 `path(...)` and Style 2 `api_path(...)` definitions register into the same `MetadataStore`, so a single schema file holds paths contributed by either DSL.
 
-Here the guards described above stop being optional: without them both test frameworks wire themselves into Rails' lazy-load hooks in the same process.
+Here the guards described above carry more weight: without them both test frameworks wire themselves into Rails' lazy-load hooks in the same process. Guard what you can — but the "When guarding backfires" rules still apply, so a helper your suite leans on at load time stays unguarded even in hybrid mode.
 
 ```ruby
 # test/test_helper.rb
@@ -531,7 +607,198 @@ end
 
 `OpenapiRuby.schema_generating?` returns `true` when the rake task launched the current process (it sets `OPENAPI_RUBY_GENERATING=true` in the subprocess). With the guards in place, neither test framework boots its full Rails integration during generation — only the DSL needs to be live for `api_path` / `path` to register.
 
-Once the migration completes and only one test framework remains, the rake task auto-detects that framework. The guard is then no longer *required* — but it's still worth keeping for the reasons in "Making generation cheaper" above.
+Once the migration completes and only one test framework remains, the rake task auto-detects that framework, and the guard goes back to being a pure optimization.
+
+## Host Frameworks
+
+Rails picks up its wiring from the engine. Every other host makes the same calls itself — the gem only ever needs a Rack middleware stack, a way to mount a Rack app, and rack-test.
+
+| | Rails | Hanami | Sinatra / Roda / bare Rack |
+|---|---|---|---|
+| Test DSL + generation | ✅ | ✅ | ✅ |
+| Runtime validation middleware | automatic | one call | one call |
+| Schema + Swagger UI endpoints | `mount OpenapiRuby::Engine` | `mount OpenapiRuby::RackApp` | `map`/`run OpenapiRuby::RackApp` |
+| `openapi_ruby:install` / `:component` generators | ✅ | — | — |
+| `openapi_permit` strong params | ✅ | — | — |
+
+Versions covered by CI: Rails 7.0–8.0, Hanami 2.3 and 3.0, Sinatra 3.2 and 4.2. Working reference apps live in [`spec/dummy`](spec/dummy), [`spec/hanami_dummy`](spec/hanami_dummy), and [`spec/sinatra_dummy`](spec/sinatra_dummy).
+
+### Hanami
+
+**1. Configure.** Anywhere that loads before your app class — `config/openapi_ruby.rb` is a natural home:
+
+```ruby
+require "openapi_ruby/hanami"
+
+OpenapiRuby.configure do |config|
+  config.schemas = {
+    public_api: {
+      info: { title: "My API", version: "v1" },
+      servers: [{ url: "/api/v1" }],
+      prefix: "/api/v1" # scopes the validation middleware to the API
+    }
+  }
+end
+```
+
+Components default to `config/api_components/` on Hanami instead of `app/api_components/`. Zeitwerk owns everything under `app/` and expects `app/api_components/schemas/user.rb` to define `MyApp::ApiComponents::Schemas::User`, while the component loader requires the file directly — which loads fine in tests and fails on eager load in production. Keeping components outside the autoload roots avoids the clash; openapi_ruby warns if `component_paths` points inside `app/`.
+
+**2. Install the middleware** (only needed for runtime validation) in `config/app.rb`:
+
+```ruby
+require "hanami"
+require_relative "openapi_ruby"
+
+module MyApp
+  class App < Hanami::App
+    # Declared before :body_parser so the validation middleware reads and
+    # rewinds the request body first.
+    OpenapiRuby::Hanami.install_middleware!(config)
+
+    config.middleware.use :body_parser, :json
+  end
+end
+```
+
+**3. Mount the docs endpoints** in `config/routes.rb`:
+
+```ruby
+module MyApp
+  class Routes < Hanami::Routes
+    mount OpenapiRuby::RackApp, at: "/api-docs"
+  end
+end
+```
+
+For request specs, `require "openapi_ruby/rspec"` wires rack-test into `type: :openapi` example groups and points it at `Hanami.app`:
+
+```ruby
+# spec/spec_helper.rb
+ENV["HANAMI_ENV"] ||= "test"
+
+require "hanami/prepare"
+require "openapi_ruby/rspec"
+```
+
+Define `let(:app)` in a group to drive a slice instead of the whole app.
+
+### Sinatra, Roda, and bare Rack
+
+Nothing here is Sinatra-specific — it is the same three steps against a plain Rack app.
+
+**1. Configure**, and say where components live. There is no autoload convention to infer one from:
+
+```ruby
+# config/openapi_ruby.rb
+require "openapi_ruby"
+
+OpenapiRuby.configure do |config|
+  config.schemas = {
+    public_api: {
+      info: { title: "My API", version: "v1" },
+      servers: [{ url: "/api/v1" }],
+      prefix: "/api/v1"
+    }
+  }
+
+  config.component_paths = ["api_components"]
+end
+```
+
+**2. Install the middleware** onto the app's stack. `Installer#install!` takes anything that responds to `use`, which a `Sinatra::Base` subclass does:
+
+```ruby
+class App < Sinatra::Base
+  OpenapiRuby::Middleware::Installer.install!(self, root: __dir__)
+
+  # ... routes
+end
+```
+
+For Roda or bare Rack, hand it the builder instead — `OpenapiRuby::Middleware::Installer.install!(builder, root: __dir__)` inside `Rack::Builder.new { ... }`.
+
+**3. Mount the docs endpoints** in `config.ru`:
+
+```ruby
+require_relative "app"
+
+map "/api-docs" do
+  run OpenapiRuby::RackApp
+end
+
+map "/" do
+  run App
+end
+```
+
+For request specs, `require "openapi_ruby/rspec"` includes rack-test for you; naming the app is the only wiring left, since no Rack host has a convention for which app is under test:
+
+```ruby
+# spec/spec_helper.rb
+ENV["APP_ENV"] ||= "test"
+
+require_relative "../app"
+require "openapi_ruby/rspec"
+
+module AppUnderTest
+  def app
+    App
+  end
+end
+
+RSpec.configure do |config|
+  config.include AppUnderTest, type: :openapi
+end
+```
+
+Minitest is the same shape — including the DSL brings rack-test with it, and the class defines `app`:
+
+```ruby
+class ApiTest < Minitest::Test
+  include OpenapiRuby::Adapters::Minitest::DSL
+
+  def app
+    App
+  end
+end
+```
+
+> **Getting 403 "Host not permitted"?** Sinatra only relaxes its host authorization outside `development`, and rack-test sends `Host: example.org`. Set `APP_ENV=test` (or `RACK_ENV=test`) in your test helper — the snippet above does.
+
+### Specs and generation on every host
+
+Specs are written identically regardless of host, in either DSL style:
+
+```ruby
+RSpec.describe "Posts API", type: :openapi do
+  openapi_schema :public_api
+
+  api_path "/posts" do
+    get "List posts" do
+      tags "Posts"
+      produces "application/json"
+
+      response 200, "returns posts" do
+        schema type: :array, items: { "$ref" => "#/components/schemas/Post" }
+      end
+    end
+  end
+
+  it "returns all posts" do
+    assert_api_response :get, 200 do
+      expect(parsed_body.length).to eq(2)
+    end
+  end
+end
+```
+
+The Rails engine loads the rake task on its own. Elsewhere, add it to your Rakefile:
+
+```ruby
+require "openapi_ruby/rake_tasks"
+```
+
+`bundle exec rake openapi_ruby:generate` then behaves as it does on Rails. It detects the host and sets the environment variable that host reads — `RAILS_ENV`, `HANAMI_ENV`, or `APP_ENV`/`RACK_ENV` — for the generation subprocess.
 
 ## Runtime Middleware
 
@@ -573,7 +840,7 @@ Mount the engine to expose the schema endpoints:
 mount OpenapiRuby::Engine => "/api-docs"
 ```
 
-Schema files are served at `/api-docs/schemas/:name`.
+Schema files are served at `/api-docs/schemas/:name`. On any other host, mount `OpenapiRuby::RackApp` instead — see [Host Frameworks](#host-frameworks).
 
 To also serve the interactive Swagger UI at the mount root, opt in:
 

data/Rakefile

@@ -5,4 +5,36 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+# Each alternate host's dummy app runs in its own bundle, so Rails and the
+# other framework never have to boot in one process.
+#
+# Unbundled: Bundler exports BUNDLE_LOCKFILE next to BUNDLE_GEMFILE, and an
+# inherited one makes the child write its resolution into this bundle's
+# Gemfile.lock.
+def run_dummy_app_specs(gemfile, dir, command)
+  gemfile_path = File.expand_path("gemfiles/#{gemfile}", __dir__)
+
+  Bundler.with_unbundled_env do
+    Dir.chdir(dir) do
+      sh({"BUNDLE_GEMFILE" => gemfile_path}, command)
+    end
+  end
+end
+
+namespace :spec do
+  desc "Run the Hanami dummy app's specs in the Rails-free bundle"
+  task :hanami do
+    run_dummy_app_specs("hanami.gemfile", "spec/hanami_dummy", "bundle exec rspec")
+  end
+
+  desc "Run the Sinatra dummy app's specs and tests in the Rails-free bundle"
+  task :sinatra do
+    run_dummy_app_specs("sinatra.gemfile", "spec/sinatra_dummy", "bundle exec rspec")
+    run_dummy_app_specs("sinatra.gemfile", "spec/sinatra_dummy", "bundle exec ruby -Itest test/posts_test.rb")
+  end
+
+  desc "Run every host's dummy app suite"
+  task hosts: %i[hanami sinatra]
+end
+
 task default: :spec

data/app/controllers/openapi_ruby/schemas_controller.rb

@@ -3,56 +3,15 @@
 module OpenapiRuby
   class SchemasController < ActionController::API
     def show
-      schema_name = params[:id]
-      config = OpenapiRuby.configuration
+      document = Serving.schema_document(params[:id], request: request)
+      return head :not_found unless document
 
-      schema_config = config.schemas[schema_name.to_sym]
-      return head :not_found unless schema_config
-
-      file_path = schema_file_path(schema_name)
-      return head :not_found unless file_path && File.exist?(file_path)
-
-      content = File.read(file_path)
-
-      # Apply filter if configured
-      if schema_config[:openapi_filter]
-        doc = parse_content(file_path, content)
-        schema_config[:openapi_filter].call(doc, request)
-        content = serialize_doc(file_path, doc)
-      end
-
-      content_type = file_path.end_with?(".json") ? "application/json" : "application/x-yaml"
+      content, content_type = document
       render plain: content, content_type: content_type
     end
 
     def index
-      schemas = OpenapiRuby.configuration.schemas.keys.map(&:to_s)
-      render json: {schemas: schemas}
-    end
-
-    private
-
-    def schema_file_path(schema_name)
-      config = OpenapiRuby.configuration
-      ext = (config.schema_output_format == :json) ? "json" : "yaml"
-      path = Rails.root.join(config.schema_output_dir, "#{schema_name}.#{ext}")
-      path.to_s
-    end
-
-    def parse_content(file_path, content)
-      if file_path.end_with?(".json")
-        JSON.parse(content)
-      else
-        YAML.safe_load(content, permitted_classes: [Date, Time])
-      end
-    end
-
-    def serialize_doc(file_path, doc)
-      if file_path.end_with?(".json")
-        JSON.pretty_generate(doc)
-      else
-        doc.to_yaml
-      end
+      render json: {schemas: Serving.schema_names}
     end
   end
 end

data/app/controllers/openapi_ruby/ui_controller.rb

@@ -5,83 +5,26 @@ module OpenapiRuby
     layout false
 
     def index
-      config = OpenapiRuby.configuration
-      @schemas = config.schemas
-      @ui_config = config.ui_config
-
-      render html: swagger_ui_html.html_safe
+      html = Serving.swagger_ui_html(
+        schema_urls: schema_urls,
+        ui_config: OpenapiRuby.configuration.ui_config
+      )
+      render html: html.html_safe
     end
 
     def oauth2_redirect
-      file = File.join(OpenapiRuby::Engine.root, "app", "views", "openapi_ruby", "oauth2_redirect.html")
-      render file: file, layout: false, content_type: "text/html"
+      render file: Serving.oauth2_redirect_file, layout: false, content_type: "text/html"
     end
 
     private
 
-    def schema_format
-      (OpenapiRuby.configuration.schema_output_format == :json) ? :json : :yaml
-    end
-
-    def swagger_ui_html
-      <<~HTML
-        <!DOCTYPE html>
-        <html lang="en">
-        <head>
-          <meta charset="UTF-8">
-          <title>#{@ui_config[:title] || "API Documentation"}</title>
-          <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
-          <style>
-            html { box-sizing: border-box; overflow-y: scroll; }
-            *, *:before, *:after { box-sizing: inherit; }
-            body { margin: 0; background: #fafafa; }
-          </style>
-        </head>
-        <body>
-          <div id="swagger-ui"></div>
-          <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
-          <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
-          <script>
-            SwaggerUIBundle({
-              #{schema_urls_js},
-              dom_id: '#swagger-ui',
-              deepLinking: true,
-              presets: [
-                SwaggerUIBundle.presets.apis,
-                SwaggerUIStandalonePreset
-              ],
-              plugins: [
-                SwaggerUIBundle.plugins.DownloadUrl
-              ],
-              layout: "#{(@schemas.size > 1) ? "StandaloneLayout" : "BaseLayout"}",
-              #{ui_config_js}
-            });
-          </script>
-        </body>
-        </html>
-      HTML
-    end
-
-    def schema_urls_js
-      fmt = schema_format
-      if @schemas.size > 1
-        urls = @schemas.map { |name, schema_config|
-          title = schema_config.dig(:info, :title) || name.to_s
-          url = openapi_ruby.schema_path(name.to_s, format: fmt)
-          {url: url, name: title}
+    def schema_urls
+      OpenapiRuby.configuration.schemas.map do |name, schema_config|
+        {
+          url: openapi_ruby.schema_path(name.to_s, format: Serving.schema_format),
+          name: schema_config.dig(:info, :title) || name.to_s
         }
-        "urls: #{urls.to_json}"
-      else
-        name = @schemas.keys.first.to_s
-        url = openapi_ruby.schema_path(name, format: fmt)
-        "url: \"#{url}\""
       end
     end
-
-    def ui_config_js
-      @ui_config.except(:title).map { |k, v|
-        "#{k}: #{v.to_json}"
-      }.join(",\n          ")
-    end
   end
 end

data/lib/openapi_ruby/adapters/context_resolution.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Adapters
+    # Shared by the Minitest and RSpec Style 2 adapters.
+    #
+    # Style 2 separates the `api_path` declaration from the request that
+    # exercises it, so the request has to be matched back to a declaration.
+    # Everything used to do that here is a hard fact about the request, never a
+    # guess: the verb, which path params the template needs against which the
+    # caller supplied, whether the candidate declares the status the assertion
+    # demands, and whether the remaining params are declared on the operation.
+    #
+    # That leaves one case it cannot decide. `/timers/{id}` and
+    # `/timers/{id}/start` under the same verb, the same status and the same
+    # `{id}` are indistinguishable from the call site — the information simply
+    # isn't there. Picking one silently sends the request to the wrong endpoint
+    # and validates it against the wrong response schema, so a test passes while
+    # exercising something else. Raise instead, and name the candidates; the
+    # author resolves it by passing `api_path:` or by scoping the declarations.
+    module ContextResolution
+      module_function
+
+      def resolve(contexts, method, path_params, owner:, params: {}, expected_status: nil, api_path: nil)
+        if api_path
+          selected = find_declared(contexts, api_path)
+          raise OpenapiRuby::Error, unknown_path_message(contexts, api_path, owner) unless selected
+          return selected
+        end
+
+        candidates = contexts.select { |ctx| ctx.operations.key?(method.to_s) }
+        return candidates.first if candidates.size <= 1
+
+        supplied = keys_of(params) | keys_of(path_params)
+        required = keys_of(path_params)
+
+        candidates = narrow(candidates) { |ctx| path_params_fit?(ctx, required, supplied) }
+        if expected_status
+          candidates = narrow(candidates) { |ctx| declares_status?(ctx, method, expected_status) }
+        end
+        candidates = fewest_unaccounted(candidates, method, supplied)
+
+        return candidates.first if candidates.size == 1
+
+        raise OpenapiRuby::AmbiguousApiPath, ambiguity_message(candidates, method, owner)
+      end
+
+      # A template only fits if it needs no path param the caller did not supply,
+      # and uses every param the caller explicitly declared as one.
+      def path_params_fit?(context, required, supplied)
+        template = template_params(context)
+
+        (required - template).empty? && (template - supplied).empty?
+      end
+
+      def declares_status?(context, method, expected_status)
+        context.operations[method.to_s].responses.key?(expected_status.to_s)
+      end
+
+      # Prefer the candidate that can explain the most supplied keys as either a
+      # path param of its own template or a parameter declared on it. A key that
+      # fits nowhere means the request was probably meant for a sibling path.
+      def fewest_unaccounted(candidates, method, supplied)
+        ranked = candidates.group_by { |ctx| (supplied - accounted_keys(ctx, method)).size }
+
+        ranked[ranked.keys.min]
+      end
+
+      def accounted_keys(context, method)
+        declared = context.path_parameters + (context.operations[method.to_s]&.parameters || [])
+
+        template_params(context) | declared.filter_map { |param| param["name"]&.to_s }
+      end
+
+      def template_params(context)
+        context.path_template.scan(/\{(\w+)\}/).flatten
+      end
+
+      def find_declared(contexts, api_path)
+        template = api_path.respond_to?(:path_template) ? api_path.path_template : api_path.to_s
+
+        contexts.find { |ctx| ctx.path_template == template }
+      end
+
+      def narrow(candidates)
+        narrowed = candidates.select { |ctx| yield(ctx) }
+
+        narrowed.empty? ? candidates : narrowed
+      end
+
+      def keys_of(params)
+        params.keys.map(&:to_s)
+      end
+
+      def ambiguity_message(matches, method, owner)
+        paths = matches.map { |ctx| ctx.path_template.inspect }.join(", ")
+
+        "#{method.to_s.upcase} matches more than one api_path in #{owner}: #{paths}. " \
+          "Requests are matched on the verb, the path params supplied and the declared " \
+          "response status, none of which tell these apart. Pass api_path: to pick one, " \
+          "or declare each api_path in its own class or nested describe block."
+      end
+
+      def unknown_path_message(contexts, api_path, owner)
+        template = api_path.respond_to?(:path_template) ? api_path.path_template : api_path.to_s
+        declared = contexts.map { |ctx| ctx.path_template.inspect }.join(", ")
+
+        "No api_path #{template.inspect} declared in #{owner}. " \
+          "Declared: #{declared.empty? ? "none" : declared}."
+      end
+    end
+  end
+end