Refactor DSL::Routing#version: guard clause, explicit kwargs, value object

[ericproulx]

Summary

Three changes to Grape::DSL::Routing#version plus the call sites and middleware that consume its output:

1. Guard clause

if args.any? ... end wrapping a 20-line body → return @versions&.last if args.empty?.

2. Explicit kwargs in place of **options

def version(*args, using: :path, cascade: true, parameter: 'apiver', strict: false, vendor: nil, &block)

Defaults live in the signature instead of being applied later via reverse_merge + the versioner's deep-merged DEFAULT_OPTIONS. The per-call reverse_merge is gone.

3. Grape::DSL::VersionOptions value object, threaded end-to-end

New file lib/grape/dsl/version_options.rb:

VersionOptions = Data.define(:using, :cascade, :parameter, :strict, :vendor)

• #version builds and stores a VersionOptions on inheritable_setting.namespace_inheritable[:version_options].
• Path#uses_path_versioning?, Endpoint#build_stack, and API::Instance#cascade? read fields via accessors instead of [:key].
• The versioner middleware (Versioner::Base) now takes the VersionOptions directly, not a Hash. Forwardable.def_delegators forwards cascade / parameter / strict / vendor to it; the four ivars and per-call assignments in #initialize are dropped. DEFAULT_OPTIONS stores VersionOptions.new(...) so direct-mount callers still get safe defaults.

Public .version DSL surface is unchanged — still accepts kwargs the same way; the value object is an internal-only representation.

version_options is read for exactly these five keys across the codebase, and nothing else:

Key	Read at
:using	endpoint.rb, path.rb
:cascade	Versioner::Base, API::Instance#cascade?
:parameter	Versioner::Base
:strict	Versioner::Base
:vendor	Versioner::Base

Any other kwarg passed to .version was previously swallowed by **options with no effect — now ArgumentError.

Spec fixtures updated

• spec/shared/versioning_examples.rb — 14 sites changed **macro_options → **macro_options.except(:format). The :format key stays in the macro hash so versioned_helpers.rb can still build the HTTP_ACCEPT header.
• spec/grape/exceptions/invalid_accept_header_spec.rb — dropped format: :json from 8 direct .version calls.
• spec/grape/dsl/routing_spec.rb — :version_options assertion now expects a VersionOptions instance.
• spec/grape/path_spec.rb — literal hashes → VersionOptions.new(...).
• spec/grape/middleware/versioner/{header,accept_version_header,param}_spec.rb — fixtures construct VersionOptions instances; mid-test @options[:version_options][:strict] = X mutations rewritten as @options[:version_options] = @options[:version_options].with(strict: X) (Data instances are immutable).

Why format: was in the specs (and why dropping it from .version is correct)

Several specs passed format: :json (or format: 'json' in macro_options) directly to .version. This was test-fixture double-duty, never a real .version feature:

• spec/support/versioned_helpers.rb's versioned_headers builds the request HTTP_ACCEPT header from the same hash: for header versioning it produces application/vnd.#{vendor}-#{version}+#{format}. So :format exists for the test helper to construct the request's Accept header.
• The specs reused one options hash for two unrelated jobs — configuring the API (subject.version 'v1', **macro_options) and driving the request (versioned_get '/x', 'v1', macro_options) — so :format rode into .version purely as a side effect of the splat.

.version never had a format: option. Its value lands in namespace_inheritable[:version_options], and the versioner middleware only ever reads :cascade / :parameter / :strict / :vendor from it — nothing reads version_options[:format]. For header versioning the response format is parsed out of the request Accept header (media_type.format → env['api.format']); the API's serialization format is set independently by format / default_format. So under the old **options splat, format: on .version was silently swallowed and inert.

The fix preserves intent exactly:

• spec/shared/versioning_examples.rb — .version is called with **macro_options.except(:format) (drops the inert kwarg), but versioned_get still receives the full macro_options, so the request Accept header is still application/vnd.mycompany-v1+json — byte-identical to before. The header-versioning + format-negotiation path is genuinely still exercised.
• spec/grape/exceptions/invalid_accept_header_spec.rb — format: :json dropped from direct .version calls; those tests build their Accept header inline, so it was equally dead there.

Verified: header-versioning shared examples 12/0; invalid_accept_header_spec.rb + all spec/grape/middleware/versioner specs 110/0. Same requests sent, same behaviour — only a silent no-op kwarg on .version is now (correctly) an explicit ArgumentError.

Behaviour change

No production behaviour change beyond .version raising ArgumentError for genuinely unknown kwargs (previously silently ignored — see the format: note above for the canonical example).

Documented in UPGRADING.md under ### Upgrading to >= 3.3 → "version now takes explicit keyword arguments", with the recognised-key list and the format: before/after.

Test plan

• Full suite: bundle exec rspec — 2292 examples, 0 failures
• RuboCop clean on touched files
• CI green across Gemfile variants

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run