# ADR-0003: OpenAPI-first API documentation via route schemas

**Status:** Accepted

## Context

Hand-written API reference docs rot the moment an endpoint changes. We need a
reference that is always accurate, machine-readable for client/SDK generation,
and interactive for exploration — without a separate authoring burden.

## Decision

Treat the **route schemas as the single source of truth** and generate OpenAPI
from them:

- Every route declares a Fastify `schema` (tags, summary, description, params,
  body, response shapes). `@fastify/swagger` derives an OpenAPI **3.1** document
  from these at runtime; `@fastify/swagger-ui` serves an interactive console at
  `/docs` and the raw spec at `/docs/json`.
- The `BearerAuth` JWT scheme and per-domain tags are declared centrally in
  `src/plugins/swagger.ts`.
- A contract test (`test/integration/openapi.integration.spec.ts`) fails the
  build unless the generated spec stays complete — OpenAPI 3.1, the security
  scheme, all domain tags, ≥ 20 paths, and **every operation carrying a summary,
  tag, and response**.

## Consequences

- **+** The reference can never silently drift from the implementation; an
  undocumented endpoint breaks CI.
- **+** Clients/SDKs can be generated from `/docs/json`.
- **+** No parallel doc-authoring effort; documentation is a side-effect of
  writing well-schematised routes.
- **−** Routes must be disciplined about attaching complete schemas — enforced
  by the contract test rather than left to good intentions.
