ADR 0022: Embedded Swagger — static OpenAPI validation (superseded)

Ratification

This ADR records a superseded decision (see below). The latest merge updated that story; ratification follows ADR 0018.

• Discussion Issue: none linked for this merge
• Merge PR: see git history for this file
• Accepted: 2026-04-12

Context (historical)

Why this record exists: We tried static Swagger UI plus browser JSON validation so the docs site could act like a small “Postman” without a server. That helps onboarding in theory; in practice CORS, Swagger versions from a CDN, file:// browsing, and OpenAPI $ref handling made the page brittle and hard to keep working.

The original goal was to embed Swagger UI against docs/openapi/openapi-baseline.json (see ADR 0007) and add browser-side validation of JSON bodies (Ajv, interceptors, no live HTTP from that page).

Superseded decision

The approach described in earlier drafts of this ADR — static validation of application/json bodies in the browser via Ajv, Swagger requestInterceptor / responseInterceptor, and related client-side wiring — is cancelled as a product commitment. It proved brittle (CDN loading, file://, Swagger UI versions, ref resolution) and did not deliver a reliable experience.

What was implemented instead

docs/openapi/openapi-explorer.html is labeled OpenAPI (test) in the docs nav. It loads Swagger UI from the CDN and points at the committed openapi-baseline.json for visual exploration only: operations, schemas, and documentation text. Try it out is disabled on this page. No validation runs in the browser; there is no Ajv/ref-parser bundle and no openapi-sandbox.js.

For real HTTP Try it out against a running server, use the application’s interactive docs at /docs (configure CORS for your browser origin).

On hold

A future iteration may revisit browser-side or docs-integrated contract validation (static or against a mock), with clearer scope and tooling. Until then the task is on hold. Contract correctness remains enforced by make contract-test / CI on openapi-baseline.json, not by this page.

Consequences

• Readers still get a quick visual view of the OpenAPI snapshot from the static site.
• No claim of client-side validation; no maintenance burden for the previous interceptor/Ajv stack.
• ADR 0007 / governance of the baseline file is unchanged.

References

• Related: ADR 0007, ADR 0001.
• Page: docs/openapi/openapi-explorer.html (OpenAPI test).

Page history