One OpenAPI spec, every surface
How the API contract drives the docs, the endpoint pages and the machine-readable files we publish.
{
"legal_name": "Acme Studio Ltd",
"company_number": "01234567",
"status": "active"
}The API contract is the single source of truth. Everything a developer reads is generated from it or validated against it: the reference docs, the endpoint pages and the machine-readable files.
The contract
corpo_openapi.yaml is an OpenAPI 3.1 document. It defines the request and response shapes for every operation: authentication, pagination, the error schema, and the freshness block that says where a record came from. Build teams code against that file, not against a prose description that drifts from the code.
The surfaces
From one contract we derive several things:
- The reference docs are generated from the spec, so a schema change appears in the docs the moment it lands.
- The endpoint pages under
/endpointsdescribe the same operations, with the price taken fromcontent/pricing.yaml. llms.txt,robots.txtandpricing.mdare written on every build from the same site data, so an LLM or a crawler reads the same facts a human does.
Why generate instead of hand-write
A hand-maintained pricing table is a table that goes stale. A hand-written error list is a list that drifts from the codes the server actually returns. Generating the machine-facing surfaces from one source removes that class of bug: the endpoint page, the JSON-LD, the pricing.md line and the API itself cannot disagree.
The tradeoff is that the source has to be real. If the spec is wrong, every surface is wrong in the same way, which is at least a single place to fix.