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/swaggerderives an OpenAPI 3.1 document from these at runtime;@fastify/swagger-uiserves an interactive console at/docsand the raw spec at/docs/json. - The
BearerAuthJWT scheme and per-domain tags are declared centrally insrc/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.