Eve library

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

ADR

Revision 1

On this page

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.