Description
The OpenAPI Contract publishes the documented Dots HTTP surface as an OpenAPI 3.1 document at /api/v1/openapi.json. Route modules declare request parameters, bodies, response envelopes, and error outcomes with Zod-backed OpenAPI definitions, and the application generates the document from the same registered routes that handle requests.
Before serving, the generator strips the explicit internal-route roster so operator-only or implementation-control endpoints do not become advertised SDK surface. Census tests compare live routes, documented routes, internal enrollment, and schema coverage, catching a new endpoint that was implemented without documentation or an internal endpoint accidentally exposed in the contract.
Selling Points
- Gives integrators a machine-readable API catalog for client generation, exploration, and contract testing.
- Derives documentation from runtime route definitions, reducing drift between prose and actual validation.
- Keeps internal control endpoints out of the public document through an explicit, tested roster.
- Describes standard data and error envelopes, helping clients handle Dots APIs consistently.
- Covers self-hosted and hosted deployments because both serve the same application contract.
User Story
An integration developer points an OpenAPI client generator at their Dots deployment. They receive the public route catalog, including schemas for publications, rows, search, and health, while daemon shutdown and other internal controls are absent. They generate typed client scaffolding and use the document to validate requests against the deployed server.
Extension Surface
This feature is automatable. packages/api/src/openapi.ts serves a stable machine-readable document, and external tools can fetch it in CI, SDK generation, or API explorers. Route authors extend the document inside the repository by registering documented routes. There is no runtime plugin hook for arbitrary OpenAPI fragments, so the feature is not rated pluggable.
Capabilities & Limits
- Emits OpenAPI 3.1 with request, response, and error schemas for documented routes.
- Strips the closed
INTERNAL_ROUTESroster before returning the public document. - Uses route and coverage censuses to detect undocumented or improperly tiered operations.
- Limit: method-ALL and conditionally mounted control surfaces may intentionally sit outside the documented public catalog.
- Limit: the document describes HTTP contracts, not business authorization available to a particular credential.
Implementation Map
packages/api/src/openapi.tspackages/api/src/routes/index.tspackages/api/src/routes/internal-routes.tspackages/api/src/openapi.census.test.tspackages/api/src/routes/openapi-coverage.census.test.ts