Complete OpenAPI/Swagger documentation

[karutoil]

Summary

fastify-swagger and fastify-swagger-ui are already registered in the backend (/docs endpoint), but route schemas are incomplete. Many endpoints lack proper request/response schemas, making the auto-generated OpenAPI spec incomplete.

Current State

• @fastify/swagger configured in src/index.ts with basic OpenAPI 3.0 metadata
• @fastify/swagger-ui serves interactive docs at /docs
• Input validation uses Zod schemas (src/lib/validation.ts) but these aren't consistently wired into Fastify route schema definitions
• Some routes define schema in their route options, many don't
• The spec currently shows endpoints but with generic/empty response models

Requirements

• Add complete schema objects to all route definitions (100+ endpoints across auth, servers, nodes, templates, backups, alerts, roles, admin, etc.)
• Define shared schema components: User, Server, Node, Backup, Error, Pagination, etc.
• Map Zod schemas to JSON Schema (already using zod-to-json-schema as a dependency)
• Include authentication requirements per endpoint (session, API key, public)
• Document WebSocket protocol message types (not REST, but reference from OpenAPI x-websocket extension)
• Document SSE endpoints with appropriate streaming response schemas

Acceptance Criteria

• All 100+ REST endpoints have complete request/response schemas in the OpenAPI spec
• Shared component schemas for all major models
• Authentication requirements documented per endpoint
• /docs UI shows complete, navigable API reference
• OpenAPI spec validates against the 3.0.x spec (no schema errors)
• Spec downloadable at /docs/json for external tooling consumption

[karutoil]

@pullfrog has there been any progress on this on our main branch to get this implemented.

[pullfrog]

Short answer: scaffolding exists on main, but the acceptance criteria are not met. Live OpenAPI schemas on routes have not been implemented.

What’s on main today

Piece	Status
@fastify/swagger + @fastify/swagger-ui at /docs	Present (catalyst-backend/src/index.ts) — basic title/description/version only
Zod → JSON Schema helpers	Present (openapi-helpers.ts, route-decorator.ts) but unused by any route
Offline generator scripts	Present under catalyst-backend/scripts/ (add-schemas.ts, add-inline-schemas.ts, extract-routes.ts, generate-api-docs.ts, …)
Human-written API markdown	Present (docs/api-reference.md, large) — not the Fastify OpenAPI spec
Fastify schema: on route definitions	0 of ~260 route registrations
Shared OpenAPI components / security schemes	Missing from swagger config
docs/openapi.json	Not checked in
Linked PRs / commits closing this issue	None (no cross-refs on the issue)

Acceptance criteria vs reality

• All REST endpoints have complete request/response schemas → no (zero routes wired)
• Shared component schemas → helpers/scripts only; not registered in swagger components
• Auth requirements per endpoint → not documented in OpenAPI
• /docs complete navigable reference → endpoints may list, but models/responses stay empty/generic
• Spec validates / downloadable at /docs/json with real schemas → not meaningfully done

Bottom line

Work so far is prep (swagger plugins, conversion helpers, codemod-style scripts, markdown API reference). The core job — attaching complete schema objects to all routes so /docs is a real OpenAPI surface — still needs to be done. Issue remains open with the in-progress label, but main does not ship the feature yet.

I can open a PR to start wiring schemas if you want that next.

Task list (3/3 completed)

• Gather issue comments/events and related PR/commit history
• Audit main branch for OpenAPI/swagger schema progress
• Report findings on issue Complete OpenAPI/Swagger documentation #138

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using openai-compatible/ck-grok-4.5 ｜ 𝕏}

[karutoil]

@pullfrog, please create a plan to get this implemented.

[pullfrog]

Plan: Complete OpenAPI/Swagger documentation (#138)

Current state (baseline)

Piece	Status
@fastify/swagger + UI at /docs	Present, minimal info only
Route-level schema:	0 of ~280–300 handlers
openapi-helpers.ts / route-decorator.ts	Written, unused
Zod in lib/validation.ts	Used on a few routes via preHandlers, not Fastify schema
Offline scripts (scripts/add-inline-schemas.ts, etc.)	Catalog/stubs; wrong auth (x-api-key); miss routes/servers/
Human docs	docs/api-reference.md (~5.2k lines) — best coverage checklist today
Shared components / security schemes	Missing from swagger config

Scaffolding is ready. The work is wiring real Fastify schema objects so /docs and /docs/json are a complete OpenAPI 3 surface.

---

Design decisions (lock these first)

1. Single helper module — Merge route-decorator.ts into openapi-helpers.ts (or vice versa). Export:
   • toJsonSchema(zod)
   • errorResponse(), itemResponse(), paginatedResponse()
   • path param presets (params.serverId, etc.)
   • security presets: security.public, security.user, security.agent
2. Zod → JSON Schema — Prefer Zod as source of truth where schemas already exist; convert via existing zod-to-json-schema (Zod 4 needs the current as any path). For routes without Zod, start with hand-written JSON Schema (or add Zod first for high-value bodies).
3. Validation dual-path (critical) — Fastify will AJV-validate schema.body/params/query and can break handlers if response schemas are strict. Strategy:
   • Phase A: attach request schemas + loose response docs (type: object, additionalProperties: true or description-only) so behavior does not change.
   • Phase B (optional later): migrate off duplicate Zod preHandlers onto Fastify validation, or use a docs-only transform that does not enforce responses.
4. Auth schemes (match production, not old scripts):
   • ApiKeyBearer: Authorization: Bearer catalyst_…
   • SessionCookie: Better Auth session cookie
   • AgentNodeId + AgentNodeApiKey: X-Node-Id / X-Node-Api-Key (and document legacy headers in description)
5. Do not trust extract-routes.ts / generate-api-docs.ts as-is — they miss modular servers/* and invent x-api-key.

---

Milestone 0 — Foundation (unblocks everything)

Files: catalyst-backend/src/index.ts, src/utils/openapi-helpers.ts, delete or fold route-decorator.ts.

• Expand swagger openapi config:
  • info.version from package.json (currently hard-coded 1.0.0 vs pkg 1.15.x)
  • servers, tags (Auth, Servers, Nodes, Templates, Nests, Locations, Admin, Roles, Backups, Alerts, Tasks, API Keys, Setup, Metrics, Migration, Plugins, Public, Agent, SSE)
  • components.securitySchemes as above
  • Shared components.schemas: Error, Pagination, plus stubs for User, Server, Node, Backup, Role, Template, Location, Nest, ApiKey, Alert
• Document raw export: confirm /docs/json (swagger-ui default) and link from description to docs/api-reference.md for WS.
• Add thin route helper, e.g. documentedRoute({ tags, summary, security, body?, params?, query?, responses? }), so every route options object stays consistent.

Exit criteria: Swagger UI shows tags + Authorize button; empty/generic models still OK.

---

Milestone 1 — Shared Zod / model library

Files: src/lib/validation.ts, new src/lib/openapi-schemas.ts (or extend validation).

• Promote existing Zod: serverCreateSchema, serverCloneSchema, serverUpdateSchema, auth registration/login, role create, local schemas in api-keys, setup, plugins, network.
• Add missing request Zod (or JSON Schema) for common query patterns: pagination (page, pageSize), filters.
• Define response documentation shapes aligned with real payloads (inspect a few handlers per domain; envelopes are inconsistent — do not invent a single { success, data } if routes return raw objects).
• Export named JSON Schema components registered once in swagger components.schemas and $ref from routes.

Exit criteria: One import path for all OpenAPI building blocks; unit smoke that toJsonSchema runs on Zod 4 schemas without throw.

---

Milestone 2 — Annotate routes by domain (core work)

Attach schema: { tags, summary, security, params/query/body, response } to every Fastify registration. Prefer mechanical, PR-sized slices:

PR slice	Modules	Approx handlers	Notes
2a	auth.ts, setup.ts, api-keys.ts	~30	Existing Zod; public vs session clear
2b	servers/core.ts, power.ts, stats.ts, variables.ts	~25	Highest traffic
2c	servers/files.ts, network.ts, databases.ts, mod-plugins.ts, invites.ts, admin-ops.ts	~50	Large surface
2d	nodes.ts, templates.ts, nests.ts, locations.ts	~60	CRUD patterns
2e	backups.ts, tasks.ts, bulk-servers.ts, dashboard.ts, metrics.ts	~40
2f	admin.ts, roles.ts, alerts.ts, update.ts, admin-events REST parts	~70	Biggest admin surface
2g	migration.ts, plugins.ts, file-tunnel.ts	~25	Agent auth on tunnel
2h	Inline routes in index.ts (health, deploy, SFTP, theme, agent download, public)	~15	Mixed public/agent/user

Per-route checklist:

• Correct tag + short summary (pull from docs/api-reference.md / add-inline-schemas.ts catalog after path fix-up)
• security matches middleware (authenticate / public / agent)
• Path/query/body schemas for non-trivial inputs
• At least 200/201 + 400/401/403/404 error refs where applicable
• No behavior change (keep existing Zod/manual preHandlers until Phase B)

Better Auth catch-all /api/auth/*: do not fake full OpenAPI coverage; tag custom Fastify auth routes only; note Better Auth paths in description or externalDocs.

Exit criteria: Grep shows every app.(get|post|put|patch|delete) under src/routes and documented index.ts routes have a schema object (or explicit hide: true with justification).

---

Milestone 3 — SSE + WebSocket documentation

SSE (console-stream.ts, sse-events.ts, metrics-stream.ts, admin-events.ts):

• Document as GET with produces / response content type text/event-stream
• Component schemas for event name enums from EVENT_TYPES / ADMIN_EVENT_TYPES
• Describe payload shapes for top events (server_state_update, resource_stats, admin CRUD events)

WebSocket (GET /ws, websocket/gateway.ts, shared-types.ts WsEvent):

• OpenAPI 3.0 cannot fully model WS — use x-websocket (or similar) extension on /ws plus link to docs/api-reference.md protocol tables
• Optionally later: separate AsyncAPI doc; out of scope for first ship unless cheap

Exit criteria: SSE routes visible in /docs with stream semantics; WS documented with extension + externalDocs.

---

Milestone 4 — Spec quality, CI, cleanup

• Script scripts/dump-openapi.ts: boot app (or register routes without listen), write openapi.json from app.swagger()
• Optional commit of docs/openapi.json or generate in CI artifact
• Validate OpenAPI 3.0 (e.g. @apidevtools/swagger-parser or spectral) in CI / package.json script docs:openapi
• Fix or delete stale generators (add-schemas.ts, broken generate-quick-ref.ts); rewrite extract to walk routes/**/*.ts + index.ts if kept
• Align any remaining docs that say x-api-key to Bearer
• Manual pass: /docs navigable; sample external client can import /docs/json

Exit criteria: Spec validates; downloadable JSON has real components; acceptance checklist below green.

---

Acceptance criteria mapping

Criterion	How we hit it
All REST endpoints have request/response schemas	Milestones 2a–2h complete; coverage grep/CI count
Shared component schemas	Milestone 0–1 components.schemas
Auth requirements per endpoint	security presets on each route
/docs complete navigable reference	Tags + summaries + models
Spec validates OpenAPI 3.0.x	Milestone 4 validator
Spec at /docs/json for tooling	Swagger UI / swagger plugin export

---

Risks and mitigations

Risk	Mitigation
Strict response schemas break production replies	Loose response schemas first; no AJV response enforcement until audited
Zod 4 + zod-to-json-schema edge cases	Smoke-test conversion; fall back to hand JSON Schema for broken cases
~300 routes → huge PRs	Domain-sliced PRs; merge foundation first
Response shape inconsistency	Document actual shapes per endpoint, not one forced envelope
Dynamic plugin routes	Generic plugin API description; not every plugin endpoint
Drift from api-reference.md	Use markdown as checklist; eventually generate tables from OpenAPI

---

Suggested implementation order (effort)

1. M0 foundation (~0.5–1 day) — small PR, high leverage
2. M1 shared schemas (~1 day)
3. M2a–2b high-value routes (~2–3 days) — proves pattern
4. M2c–2h remaining REST (~1–2 weeks, parallelizable)
5. M3 SSE/WS (~1–2 days)
6. M4 CI/cleanup (~1 day)

Ship value early: after M0 + M2a/2b, /docs is already useful for auth + server core.

---

Out of scope (call out explicitly)

• Rewriting all handlers to a uniform response envelope
• Full AsyncAPI for agent WebSocket (link + extension only for v1)
• Auto-generating markdown from OpenAPI on day one (nice follow-up)
• Documenting third-party Better Auth routes in full detail

---

First concrete PR (recommended kickoff)

1. Unify helpers + security presets + shared Error/Pagination
2. Expand swagger registration in index.ts
3. Fully schema auth.ts, setup.ts, api-keys.ts, and servers/core.ts create/list/get as the template for all later slices
4. Add docs:openapi dump script and a short note in backend README pointing at /docs

No code changes in this plan run — ready to execute as Build when you want implementation started.

Task list (3/4 completed)

• Analyze OpenAPI scaffolding, helpers, and route patterns
• Inventory routes, auth patterns, SSE/WebSocket surface
• Draft structured implementation plan with milestones
• Post plan via report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using openai-compatible/ck-grok-4.5 ｜ 𝕏}