API Reference
The OpenAPI spec is generated from the live code (see Architecture Overview), so the canonical, always-current reference is served by the API itself rather than duplicated here:
| Environment | Swagger UI | Raw spec |
|---|---|---|
| Local | http://localhost:8080/v1/docs | http://localhost:8080/v1/docs/openapi.json |
| Staging | https://<staging-host>/v1/docs | https://<staging-host>/v1/docs/openapi.json |
| Production | https://<production-host>/v1/docs (Basic Auth required) | https://<production-host>/v1/docs/openapi.json (Basic Auth required) |
Production credentials are the DOCS_BASIC_AUTH_USER / DOCS_BASIC_AUTH_PASSWORD environment variables — ask in the team's usual secrets channel if you don't have them.
Coverage
Generation is incremental, not a full sweep. As of this writing, these modules have OpenAPI coverage:
| Module | Validation lane | Notes |
|---|---|---|
| User | Zod (native) | DTOs in src/modules/user/dto/user.dto.ts annotated in place |
| Payments | validatorjs (doc-only) | src/modules/payments/payments.openapi.ts |
| Events | hand-rolled validator (doc-only) | src/modules/events/event.openapi.ts |
| Guests | none at route layer (doc-only) | src/modules/guests/guests.openapi.ts |
Everything else (~55 remaining modules) doesn't have generated coverage yet. If you're working in an undocumented module and want to add it, follow the pattern in one of the files above — Zod-native modules get .openapi() calls added directly to the existing DTO; everything else gets a sibling *.openapi.ts file with doc-only schemas, registered in src/shared/openapi/build-spec.ts.
Why generated instead of hand-maintained
A hand-written spec (a YAML file nobody updates when a route changes) drifts from reality immediately. Generating it from the same Zod schemas — or Zod schemas deliberately written to mirror the real validation — means the spec can only be as stale as the last time someone touched the route without touching its schema, which a code reviewer can actually catch in a diff.