OpenAPI contracts
Combined and v2-only OpenAPI 3.1 contracts generated from the Go routes and canonical v2 DTOs.
StatsHub publishes a combined OpenAPI contract for the complete HTTP API and a
smaller contract for integrations that only use /api/v2. Both describe the
handlers served by the Go API; neither introduces a parallel implementation.
Published documents
| Location | Contents |
|---|---|
/api/openapi.json | Combined legacy /api and canonical /api/v2 contract. |
/api/openapi-v2.json | Focused v2 contract with /api/v2 as its server base. |
/api/docs | Interactive explorer served by the API process. |
/openapi.json | Combined copy published by this documentation site. |
/openapi-v2.json | V2-only copy published by this documentation site. |
/docs/api/reference | Fumadocs pages generated from the combined contract. |
The checked-in source documents live at
apps/statshub-api/docs/openapi.json and
apps/statshub-api/docs/openapi-v2.json. Reviewing an API change therefore
also reviews its contract change.
How generation works
The two surfaces use different generation strategies because they have different compatibility promises:
- Legacy
/apioperations are recovered from the existing Chi route tree and Go handlers. The generator records the exact paths, parameters, authentication helpers, request bodies, statuses, and legacy response envelopes. - Canonical
/api/v2operations are registered design-first from their real Go DTOs. Collection envelopes, Problem Details, cursor parameters, security, and write bodies are closed schemas rather than inferred maps.
The focused v2 document is merged into the combined document. V2 component names are prefixed, so an identically named legacy response cannot weaken a v2 schema.
Contract checks
Tests compare the combined document with the live Chi router in both directions. The v2 tests additionally reject:
- missing or duplicate operation IDs;
- undocumented default responses;
- open JSON success schemas;
- non-Problem JSON error schemas;
- missing authentication or write-body declarations on account operations.
Legacy conformance tests continue comparing closed success schemas with recorded response shapes. This preserves old clients while allowing v2 to use a cleaner contract.
Fumadocs generation
apps/statshub-docs/scripts/openapi.ts copies both checked-in documents into
public/. It generates one reference page per operation from the combined
document, so the sidebar covers both surfaces without duplicate pages.
Generated reference files are ignored by Git and rebuilt before development,
lint, and production builds.
Regenerating
cd apps/statshub-api
bun run openapi
bun run openapi:check
cd ../statshub-docs
bun run openapiRun the API tests and docs checks with generation. A contract is current only when the route inventory, v2 operation table, generated JSON, and published copies agree.