The contract for an API the way a Component Contract is the contract for a component: one document that every consumer reads, and that the server can be checked against.
In this site
Since #752, pnpm dev serves an OpenAPI 3.1 document for UXLab's own routes, generated by Nitro, the server engine under Nuxt:
/_openapi.json— the spec: every route Nitro finds underserver//_scalar— the Scalar reference/_swagger— Swagger UI
It is dev only. nitro.openAPI.production is false, so no deployment serves the spec. Deployed, it would list every admin and dev route to anyone who asked; turning it on means gating the three paths in shared/utils/protected-paths.ts first. Both viewers load from jsDelivr, which the site's CSP blocks, so openApiDocsRouteRules in config/security-headers.ts allows that one origin on those two paths, in dev only.
A route that declares nothing still appears, with just its path and method. A defineRouteMeta block at the top of a handler adds tags, a summary, parameters, a request body and response schemas:
defineRouteMeta({
openAPI: {
tags: ['Feed'],
summary: 'Curated feed entries for this viewer',
responses: { 200: { description: 'Feed entries, newest first' } },
},
})
It is a build-time macro, so the object must be a plain literal — no imported constants. Nitro's types want a type on every schema, and 3.1 spells a nullable field type: ['integer', 'null'], not nullable.
Nine routes are documented so far: feed, feed.xml, search, health/content, navigation, people, podcasts, tokens/validate and glossary/:slug. #753 lists the rest by tier, for choosing what comes next.
Not yet
- The Zod schemas are not the source. Handlers validate with Zod, but Nitro does not read it, so every schema in the spec is written by hand next to the code it describes and can drift from it.
- No reference pages of our own. #567 wants resource pages in the site's own design, with a generated route index. The Nitro viewers are the working reference until then.