feat(server): generate /monitors openapi spec from Zod (spike)
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.
This commit is contained in:
1 parent
ed49fd41db
commit
faedb5ba4b
8 files changed
+490
-18
No files matched your search
@@ -64,6 +64,7 @@
|
||||
"zod": "^4.3.6"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@asteasolutions/zod-to-openapi": "^8.5.0",
|
||||
"@eslint/js": "^9.17.0",
|
||||
"@types/compression": "1.8.1",
|
||||
"@types/cookie-parser": "1.4.10",
|
||||
|
||||
Reference in new issue
Block a user