Problem statement
Dockhand exposes 130+ REST API endpoints across its SvelteKit backend, but there is currently no API documentation — no Swagger UI, no OpenAPI spec, no /api-docs endpoint, and no machine-readable schema.
This creates a significant barrier for anyone trying to integrate with Dockhand programmatically (automation scripts, CI/CD pipelines, AI agents, custom tooling).
Real-world example: We spent significant time trying to configure Edge-mode Hawser tokens by calling /api/environments/{id}/... — a reasonable assumption based on how similar resources are structured. The correct endpoint turned out to be /api/hawser/tokens, which we only discovered by reading through the SvelteKit +server.ts source files. A discoverable API spec would have resolved this in minutes, not hours. (See our internal issue #813 where this was documented.)
Comparison with peer tools:
| Tool |
API Documentation |
| Portainer |
/api/docs — full Swagger UI |
| Authentik |
/api/v3/ — DRF OpenAPI schema |
| PatchMon |
/api-docs — Swagger/OpenAPI |
| Proxmox VE |
/api2/json — machine-readable API schema |
| Dockhand |
None |
Without API documentation, developers must:
- Read SvelteKit
+server.ts source files to discover endpoints
- Guess at request/response shapes
- Maintain manual, fragile endpoint references that go stale with updates
- File issues asking "how do I..." for things that would be self-explanatory with a spec
Proposed solution
Generate an OpenAPI 3.x specification from the existing SvelteKit route handlers and expose it alongside an interactive Swagger UI.
Minimum viable outcome:
- A machine-readable OpenAPI spec (JSON or YAML) at
/api/openapi.json
- An interactive Swagger UI at
/api/docs or /api-docs
- The spec stays current when API routes change (build-time or runtime generation)
Bonus:
- JSON Schema for request/response bodies
- Export endpoint for client SDK generation (TypeScript, Python, Go)
Implementation suggestions
Several approaches are viable given the SvelteKit + Bun stack:
Option A — SvelteKit OpenAPI plugin
Libraries like sveltekit-api or @sveltejs/kit route introspection hooks can generate OpenAPI specs from typed route handlers. Minimal code changes required if TypeScript types are already present.
Option B — TSDoc/JSDoc annotations on route handlers
Annotate existing +server.ts handlers with OpenAPI-compatible JSDoc comments, then use a tool like swagger-jsdoc to generate the spec at build time. Non-invasive to existing code structure.
Option C — Build-time route scanner
Scan /src/routes/api/**/+server.ts at build time, extract exported handler signatures and Zod/TypeScript types, and emit an OpenAPI spec as a static asset bundled with the app. No runtime overhead.
Option D — Manual OpenAPI YAML
Maintain a hand-written openapi.yaml alongside the routes. Least preferred — goes stale with updates and adds maintenance burden.
Recommendation: Option A or C — build-time generation with zero runtime cost, auto-updating spec, and a static asset that can be served from the existing SvelteKit static file handler.
Benefits
- API discoverability — integrators can explore the API without reading source code
- Reduced support burden — fewer "how do I call X" issues
- Client SDK generation — TypeScript/Python/Go clients can be generated from the spec
- AI agent compatibility — tools like Claude, GPT, and Cursor can consume OpenAPI specs directly for tool calling and automation
- Enterprise readiness — most enterprise procurement checklists expect API documentation
- Industry standard — OpenAPI 3.x is the de-facto standard for REST API documentation
Our current workaround
We manually extracted all 130+ endpoints from the SvelteKit source tree and maintain them as a Markdown reference in our homelab management repository. This is fragile (will go stale with every Dockhand release) and represents exactly the kind of work that a generated spec would eliminate.
We would be happy to contribute to the implementation if the maintainers are open to a PR — whether that means adding TSDoc annotations to existing handlers, wiring up a build-time generator, or standing up the Swagger UI endpoint.
Additional context
- Dockhand stack: SvelteKit + Bun runtime
- API surface: ~130+ endpoints across environments, containers, stacks, registries, agents, notifications, system settings
- No breaking changes required — this is purely additive
Problem statement
Dockhand exposes 130+ REST API endpoints across its SvelteKit backend, but there is currently no API documentation — no Swagger UI, no OpenAPI spec, no
/api-docsendpoint, and no machine-readable schema.This creates a significant barrier for anyone trying to integrate with Dockhand programmatically (automation scripts, CI/CD pipelines, AI agents, custom tooling).
Real-world example: We spent significant time trying to configure Edge-mode Hawser tokens by calling
/api/environments/{id}/...— a reasonable assumption based on how similar resources are structured. The correct endpoint turned out to be/api/hawser/tokens, which we only discovered by reading through the SvelteKit+server.tssource files. A discoverable API spec would have resolved this in minutes, not hours. (See our internal issue #813 where this was documented.)Comparison with peer tools:
/api/docs— full Swagger UI/api/v3/— DRF OpenAPI schema/api-docs— Swagger/OpenAPI/api2/json— machine-readable API schemaWithout API documentation, developers must:
+server.tssource files to discover endpointsProposed solution
Generate an OpenAPI 3.x specification from the existing SvelteKit route handlers and expose it alongside an interactive Swagger UI.
Minimum viable outcome:
/api/openapi.json/api/docsor/api-docsBonus:
Implementation suggestions
Several approaches are viable given the SvelteKit + Bun stack:
Option A — SvelteKit OpenAPI plugin
Libraries like
sveltekit-apior@sveltejs/kitroute introspection hooks can generate OpenAPI specs from typed route handlers. Minimal code changes required if TypeScript types are already present.Option B — TSDoc/JSDoc annotations on route handlers
Annotate existing
+server.tshandlers with OpenAPI-compatible JSDoc comments, then use a tool likeswagger-jsdocto generate the spec at build time. Non-invasive to existing code structure.Option C — Build-time route scanner
Scan
/src/routes/api/**/+server.tsat build time, extract exported handler signatures and Zod/TypeScript types, and emit an OpenAPI spec as a static asset bundled with the app. No runtime overhead.Option D — Manual OpenAPI YAML
Maintain a hand-written
openapi.yamlalongside the routes. Least preferred — goes stale with updates and adds maintenance burden.Recommendation: Option A or C — build-time generation with zero runtime cost, auto-updating spec, and a static asset that can be served from the existing SvelteKit static file handler.
Benefits
Our current workaround
We manually extracted all 130+ endpoints from the SvelteKit source tree and maintain them as a Markdown reference in our homelab management repository. This is fragile (will go stale with every Dockhand release) and represents exactly the kind of work that a generated spec would eliminate.
We would be happy to contribute to the implementation if the maintainers are open to a PR — whether that means adding TSDoc annotations to existing handlers, wiring up a build-time generator, or standing up the Swagger UI endpoint.
Additional context