Add OpenAPI 3.1 webhook support and per-webhook security

[andreashasse]

Phoenix integration for the webhook support and per-operation security added in andreashasse/spectra#188 and andreashasse/spectral#38.

⚠️ Blocked on both upstreams

mix.exs temporarily points :spectra and :spectral at their webhook branches with override: true (lock at spectra 1931e32, spectral c022b54). Both must be reverted to hex versions before merge, once the upstream PRs land and are released — main is on {:spectral, "~> 0.14.0"} and {:spectra, "~> 0.14.0"}.

API

Webhooks describe requests your API sends out, so they have no route in the router and are declared explicitly, as a :webhooks option in either of two places:

use PhoenixSpectral.OpenAPIController,
  router: MyAppWeb.Router,
  title: "My API",
  version: "1.0.0",
  security_schemes: %{
    "bearer_auth" => %{type: "http", scheme: "bearer"},
    "webhook_signature" => %{type: "apiKey", in: "header", name: "x-signature"}
  },
  security: [%{"bearer_auth" => []}],
  webhooks: [
    %{
      name: "userCreated",
      method: :post,
      module: MyApp.Events,
      payload: {:type, :user_created, 0},
      responses: [{200, "Acknowledged"}],
      doc: %{security: [%{"webhook_signature" => []}]}
    }
  ]

# Or directly
PhoenixSpectral.generate_openapi(MyAppWeb.Router, metadata, webhooks: webhooks)

A spec generated without the option is unchanged and emits no webhooks key (covered by a test).

The entry is a declarative map converted into a Spectral.OpenAPI webhook internally, so callers never touch the builder API that phoenix_spectral otherwise hides. A malformed entry raises FunctionClauseError rather than producing a broken spec, per the repo's crash-on-bad-code convention.

Per-webhook security

:security inside a webhook's :doc overrides the global requirement for that webhook alone; [] opts it out entirely. That is what lets the API authenticate inbound calls with a bearer token while signing outgoing webhooks with an HMAC header, as above. A webhook that declares nothing keeps inheriting the global default, which is what OpenAPI specifies — pinned by a test.

Known gap: route-based endpoints cannot set their own :security this way. Their operation docs come from the controller's spectral annotation, and spectra:function_doc() carries only summary, description and deprecated. Endpoints therefore use the global requirement. Extending the annotation path is a separate change; documented in the README rather than worked around.

Why an option and not a positional argument

This started as generate_openapi/4 taking webhooks positionally. Three problems:

• Elixir will not let /4 default its options argument while /3 exists — the default generates a dead /3 clause — so every webhook caller was forced to pass a trailing [] that did nothing.
• OpenAPIController already took webhooks: as an option, so the same data was an option in one place and a positional argument in the other.
• Arity would keep growing: top-level tags and externalDocs are both queued in spectra's todo.md.

The hazard this introduces, and the fix. Spectra reads options with proplists:get_value(pre_encoded, Options, false), which ignores keys it does not know. Carrying :webhooks in that same list means a typo like webhook: would drop every webhook from the spec in silence — the exact failure mode CLAUDE.md forbids, and one the positional form could not have. Unrecognized options therefore raise ArgumentError. That check is part of this change, not a nice-to-have.

Implementation note: the option list is split with Enum.split_with/2, not a Keyword function. Back-compat requires [:pre_encoded, webhooks: [...]] to work, and Keyword.pop/2 raises a FunctionClauseError on a list mixing bare atoms with tuples. A bare encode-option list keeps working unchanged.

Scope: :spectra_openapi.to_openapi/4 and Spectral.OpenAPI.to_openapi/4 stay positional. They are the builder layer mirroring Erlang, where webhooks are a primary input rather than an option.

Known gap

Header parameters on a webhook (documenting the X-Signature header as a parameter rather than a security scheme) are not exposed through the declarative entry. The README documents the Spectral.OpenAPI escape hatch. With per-webhook security now in place this matters less — a signature header is better described as a security scheme anyway.

Tests

Fourteen tests: top-level emission with docs and responses, payload types in components/schemas, optional responses and doc, several methods under one event name, routes still generated alongside webhooks, absence of the key when the option is omitted, a crash on a malformed entry, :webhooks coexisting with encode options in either order, a raise on an unrecognized option, a bare encode-option list still working, the :webhooks controller option served over a real conn, a webhook declaring its own auth while the API keeps the global default, [] opting out, and inheritance when nothing is declared.

Verified locally on the merge head: mix test (138 tests), mix credo --strict, mix ex_dna, mix dialyzer (0 errors), mix format --check-formatted all clean, mix compile --force --warnings-as-errors warning-free, and the example/ app's 17 integration tests pass.

Kept current with both upstreams and main

main has moved a fair way while this sat open — the 0.7.0 release, the move to the spectral 0.14 line, nil-body handling, content-type validation, and a dependency/CI upgrade. origin/main is merged in here, and both branch locks track the upstream webhook branches' own merge heads.

Conflicts were confined to the dependency pins and the changelog. mix.exs resolves to this PR's branch deps rather than main's hex versions (neither released version has webhook support yet); mix.lock and example/mix.lock take main's side wholesale and were then regenerated with mix deps.get, so the upgraded transitive deps (plug, plug_crypto, telemetry, thousand_island) are kept and only the two git deps differ from main. CHANGELOG.md keeps both this PR's ## [Unreleased] entries and the released sections below them. Everything else auto-merged, including lib/phoenix_spectral.ex, where this PR's :webhooks option plumbing sits alongside main's type-reference and content-type work.