Opt-in OpenAPI 3.0 root document (#53)

[milmazz]

Closes item 1 of #53. Stacked on #83 — re-target to main once that merges.

What's here

• openapi_version config option — "2.0" (default, byte-identical to today's PostgREST-parity Swagger document) or "3.0". A Bier extension: PostgREST core has never shipped OpenAPI 3.x (OpenAPI 3.0.0 PostgREST/postgrest#932, open since 2017). db_root_spec still overrides the document entirely.
• Bier.OpenAPI.V3.convert/1 — converts the finished Swagger 2.0 map into OpenAPI 3.0.3: definitions → components.schemas, shared params → components.parameters/components.requestBodies with schema nesting, $ref rewriting, body params → requestBody, collectionFormat: multi → style: form + explode: true, response content wrapping, servers folding from scheme/host/basePath, securityDefinitions → components.securitySchemes. Converting the finished 2.0 doc (rather than emitting 3.0 in parallel from the internal model) keeps one wire-format source of truth: every future 2.0 parity fix flows into the 3.0 output for free.
• Root wiring — build_openapi_document/2 pipes through the converter only when the instance sets openapi_version: "3.0"; negotiation, HEAD, openapi-mode, and db-root-spec precedence are untouched. An HTTP test boots a real instance and asserts the 3.0.3 wire behavior.

Notes

• The conformance instance never sets the option, so all frozen cases keep hitting the 2.0 default (suite green: 876 passed, 5 excluded; full mix precommit clean).
• 3.1 deliberately deferred: the converter architecture makes it a follow-up (one more convert variant) — per the plan's scoping decision.
• Known limitation (documented in the moduledoc): component keys inherit relation/column names verbatim; names outside OAS 3.0.3's component-key charset would produce technically invalid keys. Sanitization is out of scope for a parity-driven converter.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vdh3cbYLtKJfGkZ1ijrYGt

[milmazz]

@claude review once.

[claude]

Claude finished @milmazz's task in 3m 9s —— View job

---

Review: Opt-in OpenAPI 3.0 root document (#53 item 1)

Todo list

• Gather context (read diff, changed files, CLAUDE.md)
• Review lib/bier/openapi/v3.ex converter logic
• Review root wiring in action_controller.ex / lib/bier.ex / config.ex
• Review tests (openapi_v3_test.exs, openapi_v3_http_test.exs, config_test.exs)
• Post final review feedback

---

Nice, focused implementation — converting the finished 2.0 map instead of forking the emitter is the right call for keeping one wire-format source of truth. I traced the converter against every top-level/operation-level key the 2.0 emitter (lib/bier/openapi.ex) actually produces and didn't find a correctness bug. Elixir CI is green (so mix precommit, including credo --strict and mix docs --warnings-as-errors, already passed) — I wasn't able to re-run mix test/mix compile myself in this sandbox (no approval for mix/DB access), so I relied on that CI run plus static review.

Findings (both minor, non-blocking):

1. Small duplication — convert_body/1 (lib/bier/openapi/v3.ex:70-75) and the inline-body branch of extract_body/2 (lib/bier/openapi/v3.ex:150-153) build the exact same %{"required" => ..., "content" => %{"application/json" => %{"schema" => rewrite_refs(...)}}} shape. Since the inline RPC body (rpc_body_param/3 in openapi.ex) never sets "description", the inline branch could just call convert_body(inline) and drop the duplicate construction. Cosmetic only — behavior is identical either way.

2. collectionFormat case match is closed-world by design — convert_param/1's case Map.pop(schema_keys, "collectionFormat") do {"multi", rest} -> ...; {nil, rest} -> ... end (lib/bier/openapi/v3.ex:92-95) would raise CaseClauseError on any other collectionFormat value. This is explicitly disclosed in the moduledoc ("intentionally NOT general purpose... collectionFormat: multi only on query params") and today's emitter (Bier.OpenAPI.Types.query_param/2) only ever emits "multi", so this is a deliberate, documented scope boundary rather than a bug — just flagging it so it's a conscious tripwire if a future collectionFormat value is ever added to the 2.0 emitter without updating this converter too.

Everything else looks solid:

• $ref rewriting, definitions → components.schemas, shared parameters/body splitting, collectionFormat: multi → style/explode, response content wrapping, and servers folding all match the OAS 3.0.3 shape and are backed by good unit coverage (test/bier/openapi_v3_test.exs), including the RPC overload-winner, variadic, and security-definitions paths.
• Root wiring (action_controller.ex:197-227) cleanly gates the conversion behind config.openapi_version, leaving negotiation/HEAD/db_root_spec precedence untouched, and the HTTP test (openapi_v3_http_test.exs) exercises it against a real booted instance.
• openapi_version config option, docs (README.md, moduledocs), and .credo.exs struct-field-count bump are all consistent with the new field.
• The documented known limitation (component keys not sanitized to the OAS 3.0.3 charset) is a reasonable, clearly-scoped tradeoff for a parity-driven converter.

No blocking issues. This looks ready to merge once #83 lands and this is re-targeted to main.