The hand-maintained openapi.json has drifted significantly from the
actual API surface (PUT vs PATCH mismatches, missing query params,
stale endpoints, missing routes). This is a spike of the long-term
fix: derive the spec from the Zod validation schemas we already have.
Scope: monitors resource only. Other resources still come from the
static openapi.json — the new merger splices generated paths in and
drops the static ones the registry now owns. Migration can proceed
one resource per PR.
What this PR does:
- Adds @asteasolutions/zod-to-openapi (peerDep zod 4 satisfied).
- New src/openapi/ module:
- registry.ts — shared OpenAPIRegistry, bearerAuth scheme.
- schemas/common.ts — success/error envelope helpers.
- schemas/monitor.ts — Monitor / MonitorWithChecksList / etc.
- routes/monitor.ts — registers all 19 monitor routes against
the existing Zod validation schemas (no validation files modified).
- index.ts — getOpenApiSpec() merges generated monitor paths into
the static openapi.json and drops 2 stale entries.
- src/index.ts now calls getOpenApiSpec() instead of reading
openapi.json directly. The /api-docs Swagger UI is unchanged.
Drift fixes that fall out automatically once monitors are derived:
- PUT /monitors/{monitorId} -> PATCH (matches actual route)
- POST /monitors response 201 -> 200 (matches actual handler)
- GET /monitors/team/with-checks: 1 documented param -> 8 actual
(this is what #3354 fixed manually; now structural)
- /monitors/bulk and /monitors/test-email removed (no such routes)
- PATCH /monitors/notifications, POST /monitors/import/json, and
GET /monitors/{id}/geo-checks are now documented (were missing)
Verified by booting the merged spec in isolation: 16 monitor paths
emitted, all stale entries dropped, Monitor schema and bearerAuth
scheme registered.
Follow-ups (separate PRs):
- Migrate auth, statusPage, maintenanceWindow, notification, etc.
- Once all resources are migrated, delete the hand-edited
openapi.json and ship the generator output as the canonical doc.
- Optionally promote response shapes from passthrough() Monitor
to fully typed response Zod schemas.
