Add OpenAPI 3.1 webhook support and per-operation security

[andreashasse]

Elixir wrapper for the webhook builders and per-operation security added in andreashasse/spectra#188.

⚠️ Blocked on spectra

mix.exs temporarily points :spectra at the claude/openapi-webhook-support-sz755w branch (lock at 1931e32). This must be reverted to a hex version before merge, once andreashasse/spectra#188 lands and is released — main is on {:spectra, "~> 0.14.0"}, so this becomes whatever version ships the webhook support.

API

Spectral.OpenAPI.webhook(name, method, doc \\ %{})   # :spectra_openapi.webhook_spec()
Spectral.OpenAPI.to_openapi(metadata, endpoints, webhooks, opts)

A webhook is keyed by an event name rather than a URL path, because the consumer owns the URL the API calls. The direction is inverted relative to an endpoint: the request body is the payload the API sends out, and the responses describe what the consumer is expected to return.

endpoints_to_openapi/2,3 are unchanged and emit no webhooks key (covered by a test).

Per-operation security

The doc map for both endpoint/3 and webhook/3 now takes :security, overriding the global default for that operation; [] opts it out entirely:

metadata = %{
  security_schemes: %{
    "bearer_auth" => %{type: "http", scheme: "bearer"},
    "webhook_signature" => %{type: "apiKey", in: "header", name: "x-signature"}
  },
  security: [%{"bearer_auth" => []}]
}

webhook =
  Spectral.OpenAPI.webhook("userCreated", :post, %{
    security: [%{"webhook_signature" => []}]
  })

Why the wrapper is this small

add_response/2, with_request_body/3,4 and with_parameter/3 already pass their first argument straight through to Erlang, and spectra widened those to accept webhook_spec() as well as endpoint_spec(). Likewise endpoint/3 and webhook/3 pass the doc map through untouched, so :security needed no wrapper code at all — only the two new functions were genuinely new.

The security tests are therefore characterization tests: they prove the key survives the pass-through rather than being filtered, which isn't obvious from the code and would otherwise regress silently. They earned their keep immediately — they failed on first run because mix.lock still pinned the previous spectra commit, so the suite was quietly exercising the old dependency.

Tests

Twelve new tests: webhook construction with and without docs, building through the shared modifiers, :path/:query rejection, top-level emission, schema sharing between an endpoint and a webhook, absence of the key without webhooks, the :pre_encoded option, a webhook overriding the global security requirement, [] opting out, and an endpoint overriding it too. Plus a doctest on webhook/3.

Verified locally on the merge head: mix test (21 doctests, 3 properties, 252 tests), mix credo --strict, mix ex_dna, mix dialyzer (0 errors) and mix format --check-formatted all clean, and mix compile --force --warnings-as-errors is warning-free.

Kept current with main

main has moved twice while this sat open — 0.14.0 (spectra's nested doc annotations) and then a batch of fixes including the codec sp_type_or_ref() gap, the unexpected-crash reraise, and the [elem, ...] shorthand. origin/main is merged in here, and the :spectra lock tracks the webhook branch's own merge head.

The merge conflicts were confined to the dependency pins and the changelog: mix.exs and mix.lock resolve to this PR's branch dep rather than main's hex version (spectra 0.14.1 has no webhook support yet), and CHANGELOG.md keeps both this PR's ## [Unreleased] entries and the released sections below them. Everything else auto-merged.

A bug this caught upstream

phoenix_spectral's dialyzer found that add_response/2, with_request_body/3,4 and with_parameter/3 still declared endpoint_spec() only, even though the underlying Erlang functions had been widened to accept webhooks. Building a webhook through them was a contract violation for any caller. Fixed in 56e4091 — this repo's own dialyzer run was clean because nothing here passes a webhook to those functions.