Add Sinatra integration (OpenapiFirst::Sinatra)

[ahx]

A Sinatra extension to define routes by referencing OpenAPI operations, so URLs and HTTP methods live only in the API description:

require 'openapi_first/sinatra'

class PetsApp < Sinatra::Base
  register OpenapiFirst::Sinatra
  openapi 'openapi.yaml'

  operation(:list_pets) do |params|
    json list_pets(params[:filter])
  end
end

The HTTP method and path for each route come from the operationId. Request validation is called automatically for these operations.

Why?

• Performance: Use only Sinatra's routing instead of routing in the middleware once, then again in Sinatra
• No redundant path definition in OAD and code
• This does not add a middleware. It allows us to run request validation for some and not for other routes (good? bad?)

Related to #365

[jzobel]

Nicely done — reads clean and is unusually well-tested and documented for an experimental extension. Inline notes below; two more worth flagging beyond those:

1 (design) — routing is delegated to Sinatra/Mustermann, but validation uses the OAD template. The two matchers can diverge at the edges (trailing slash, dot-in-segment, encoding, greediness): a request Mustermann matches is validated against the template it was defined with, using the params Mustermann extracted — not openapi_first's own path matching. Fine for the covered cases; worth a docs note that the two routers' path semantics should be kept aligned. (Mustermann itself is healthy — 4.0.0, Apr 2026 — so this is about semantic divergence, not dependency risk.)

5 (minor) — build_operation_index is first-wins on duplicate operationIds (index[operation_id] ||= …): a duplicate is silently dropped. Invalid OAD, but a warn/raise would beat silent.

🤖 Generated with Claude Code

[jzobel]

parsed_body assumes an object body: Sinatra::IndifferentHash[openapi_request.parsed_body] raises for a top-level JSON array/scalar body (and for a bodyless request, where parsed_body is nil). Consider guarding for non-Hash bodies, or documenting it as object-only and pointing to openapi_request.parsed_body for arrays/scalars.
🤖 Generated with Claude Code

[jzobel]

Naming flag: route_params: → path_params: is clearer (they are path params). If Request#validate / parse_request count as public / manual-use API, this is a breaking keyword rename — worth a CHANGELOG line; ignore if they're internal.
🤖 Generated with Claude Code

[jzobel]

Formatting nits: add a blank line before ## 3.4.3, give this line a trailing period, and drop the trailing whitespace on the closing ``` fence a few lines up. (README also has trailing whitespace on the blank line inside the create_pet example, ~L442.)
🤖 Generated with Claude Code

[jzobel]

Reviewed as a downstream consumer of the gem — really solid, well-documented, and thoroughly tested. Three points worth raising (all advisory):

Classic (top-level) app auto-registration is untested

The file ends with Sinatra.register(OpenapiFirst::Sinatra), and the README/YARD both ship "in a classic app the extension registers itself, so requiring the file is enough." But every spec uses a modular Class.new(Sinatra::Base) with an explicit register, so the classic path is never exercised functionally. Because line 217 executes on require, SimpleCov reports it as covered — which makes the behavioral gap easy to miss. A shipped, documented feature with no behavioral test.

Falsy openapi_error_response falls through to the block

The handler guards with:

if (failure = validated.error) && (error_response = settings.openapi_error_response)
  halt(*error_response.new(failure:).render)
end

openapi sets that setting from OpenapiFirst.configuration.request_validation_error_response, which is user-settable to nil/false. When it's falsy, a contract-violating request skips halt and runs the block anyway, with a failed validated sitting in env[REQUEST]. This mirrors the middleware's error_response: false "disable" semantics, so it's likely intended — but it's neither tested nor documented in the Sinatra path. Worth a test that pins the intended behavior (block runs vs. request rejected).

No first-class way to override/disable the error response

The request-validation middleware exposes an explicit error_response: option (including false to disable). The Sinatra openapi method takes only spec and offers no equivalent — the only override is the undocumented set :openapi_error_response, MyClass after openapi. So there's currently no first-class way to get, say, JSON:API errors on a Sinatra app. Feature gap rather than a bug (and note the error-response class is sourced from the global config, same as the middleware — nothing consumes a per-definition request_validation_error_response, so setting it in the OpenapiFirst.load(spec) { |c| … } block is silently ignored in both paths).

🤖 Generated with Claude Code

[ahx]

@jzobel Is that you? Please mark LLM generated communication as such so people can tell if these opinions are coming from a real engineer. About the feature gap: You should still be able to configure the error response format globally. Do you think we need an additional way to configure that?

[jzobel]

Sorry for the sloppyness, I updated "my" comments.

You should still be able to configure the error response format globally.

Absolutely right, Claude and I got that wrong. Sorry for the noise!