How this reference stays true

Most API references are wrong in small ways. Not through carelessness — through ordinary drift. Someone adds a query parameter, ships it, and the docs keep describing the API as it was last quarter. Nothing looks broken, which is exactly what makes it expensive: you only find out when your integration fails against behaviour the page never mentioned.

This page explains what keeps that from happening here, because the honest answer changes how much you should trust any given part of the reference.

One document, served in two places

There is exactly one OpenAPI document. The reference pages render it, and the API serves it:

https://api.flambe.dev/openapi.json     # from the API itself
https://docs.flambe.dev/openapi.yaml    # the same document, as YAML

Byte-identical, verified on every build. That matters more than it sounds: the API used to serve a different, smaller spec — generated from code comments, describing 18 of its 131 operations. If you had found it at the conventional URL and generated a client from it, you would have got a client missing most of the API and no indication anything was missing.

What is mechanically guaranteed

Three checks run in CI on every change to the API or the docs. Each one fails the build rather than warning, because a warning in a pipeline is a warning nobody reads.

Every endpoint exists, and every endpoint is documented. A parser walks the Express application, resolves the route prefixes and the auth middleware, and produces the real list of mounted routes. That list must match the document exactly, in both directions. Add an endpoint without documenting it and the build fails; document an endpoint that does not exist and it fails too.

Every field the API validates is described. This is the subtler one. An endpoint that grows a parameter keeps the same path and method, so a route-level check sees nothing wrong — and the reference page still lists everything it knew about, so nothing looks off. The validation chains attached to each route are compared against the documented request schema, and a field the API accepts but the document omits fails the build.

Every operation says what success looks like. An operation documented with only its error responses produces a page that tells you how the call can fail and nothing about what you get back.

What it cannot tell you

Two real gaps, worth knowing rather than discovering:

Meaning is not verified. If a response field changes type, or an endpoint starts rejecting input it used to accept, no check here notices. The shape of the request is derived from code; the shape of the response is written by a person. Treat response schemas as carefully-maintained documentation rather than as a machine-verified contract.

Prose can age. The guides are written, not generated. They are the part of these docs most likely to describe how something worked six months ago — which is the tradeoff for their being useful at all. The reference is the authority when the two disagree.

Why not generate all of it from the code

It is a reasonable question, and it was the previous design.

Generating a spec from annotations gives you proximity — the description sits next to the handler, so it is hard to forget. What it costs is everything that makes a reference pleasant to read: worked examples, response unions, shared parameter definitions, and the explanation of why an endpoint behaves the way it does. Those become large comment blocks wedged between lines of application logic, and in practice they do not get written. The old generated spec covered 14% of the API, and that is the normal outcome rather than bad luck.

So the document is authored, and the guarantee that annotations were supposed to provide is enforced by the checks above instead. You get a reference someone wrote on purpose, and a build that will not let it quietly become false.

Reporting something wrong

If the reference contradicts the API, that is a bug worth reporting — it means a check has a hole in it. Get in touch, and include the endpoint and what you observed.