← 9. The API · Contents
OpenAPI reference¶
The full, browsable OpenAPI reference, every route and every request shape, is hosted on its own dedicated page:
It's generated, not written by hand: backend/src/openapi.ts is the one definition, shared by the live endpoint the backend serves at /docs and the hosted page above, so the three can never describe different APIs.
What it does not carry is the shape of a response: those come back from services typed as interfaces, which no decorator on a controller can name. Chapter 9 describes them instead.
Both pages wear the product's own chrome: the hosted one through redocly.yaml and docs/assets/redoc-template.hbs, which also self-hosts the fonts so the page depends on no CDN, and the live one through backend/src/swagger-theme.ts.
Contributors can regenerate the exported copy at docs/assets/openapi.json with pnpm run export:openapi from backend/ (make docs and CI both run this before building anything downstream of it). It compiles first, deliberately: the request shapes come from a compiler transformer that reads each DTO's TypeScript, and it only runs through nest build. The export refuses to write a document whose schemas came out empty, so losing the transformer fails the build instead of quietly publishing a reference with no fields in it.
For the rules a generated reference cannot state, the guarantees behind authentication, confinement and pagination, see 9. The API.