feat: Add OpenAPI/Swagger documentation for REST API

[strausmann]

Summary

Adds comprehensive OpenAPI 3.0 documentation for the entire Dockhand REST API — all 130+ endpoints across 24 tag groups.

• OpenAPI 3.0.3 specification as typed TypeScript object (4,000+ lines)
• JSON spec endpoint at GET /api/docs (unauthenticated)
• Interactive Swagger UI at /api/docs/ui
• 30+ reusable component schemas
• 10 validation tests using bun:test

Endpoints documented (all 130+)

Tag	#	Tag	#
Auth	8	Containers	28
Environments	14	Stacks	18
Git	12	Images	9
Hawser	3	Networks	6
Volumes	8	Prune	5
Registries	5	Notifications	6
Schedules	7	Users	5
Roles	5	Dashboard	3
Activity	4	Audit	4
System	13	Profile	6
Config Sets	5	Auto-Update	3
Health	2	Logs	1

Closes #814. Related: #815, #817

Design Decisions

• Static TypeScript spec (not swagger-jsdoc, which is CJS-only/incompatible with Bun)
• swagger-ui-dist for Swagger UI (client-side, SSR-safe)
• /api/docs in PUBLIC_PATHS (hooks.server.ts + layout.server.ts)

Files changed

File	Description
src/lib/server/openapi.ts	Full spec, all 130+ endpoints, 30+ schemas
src/routes/api/docs/+server.ts	JSON endpoint
src/routes/api/docs/ui/+page@.svelte	Swagger UI
src/hooks.server.ts	PUBLIC_PATHS
tests/openapi-spec.test.ts	10 validation tests
package.json	swagger-ui-dist

Breaking changes: None

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 3 committers have signed the CLA.

✅ strausmann
✅ itsDNNS
❌ jotka

---

strausmann seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Copilot]

Pull request overview

This PR introduces an initial OpenAPI 3.0 specification for Dockhand’s REST API and exposes it via new documentation endpoints, including a Swagger UI page for interactive exploration.

Changes:

• Adds a static TypeScript OpenAPI spec (openapiSpec) describing core API endpoints.
• Adds GET /api/docs to serve the OpenAPI JSON spec.
• Adds /api/docs/ui Swagger UI page intended to be publicly accessible and rendered without the main app layout.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/routes/api/docs/ui/+page@.svelte	Adds Swagger UI client page that loads the OpenAPI spec from /api/docs.
src/routes/api/docs/ui/+page.server.ts	Adds a server load for the docs UI route (currently informational only).
src/routes/api/docs/+server.ts	Adds /api/docs endpoint returning the OpenAPI JSON spec.
src/routes/+layout.server.ts	Adds /api/docs to a local PUBLIC_PATHS allowlist used by the layout load.
src/lib/server/openapi.ts	Introduces the OpenAPI 3.0 spec object (schemas, paths, security scheme).
package.json	Adds swagger-ui-dist and @types/swagger-ui-dist.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[strausmann]

Note on spec maintenance

The current OpenAPI spec is a static TypeScript object that must be updated manually when API routes change. This is the pragmatic starting point, but we recognize it's not ideal long-term.

Recommended next steps (not part of this PR)

1. CI validation: A build-time script that compares the routes in src/routes/api/**/+server.ts against the paths in openapi.ts and fails if endpoints are missing — this prevents the spec from going stale silently.

2. Route-to-spec generator: A script that scans the SvelteKit route tree and generates a skeleton spec, which developers then enrich with descriptions, schemas, and examples.

3. JSDoc annotations on route handlers (long-term): Once a Bun/ESM-compatible swagger-jsdoc alternative exists, annotations directly on the `+server.ts` files would be the cleanest approach — single source of truth.

We'd be happy to contribute option 1 (CI validation script) as a follow-up PR if this approach is accepted.

[strausmann]

Test-Plan (after merge)

Update

# Pull latest Dockhand with OpenAPI
ssh root@100.100.50.40 "docker pull fnsys/dockhand:latest && cd /docker/stacks/dockhand && docker compose up -d"

Verify

# 1. OpenAPI spec endpoint
curl -sf http://localhost:3000/api/docs \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'OpenAPI {d[\"openapi\"]}: {len(d[\"paths\"])} paths')"
# Expected: OpenAPI 3.0.3: 130+ paths

# 2. Swagger UI accessible
curl -sf -o /dev/null -w "HTTP %{http_code}" http://localhost:3000/api/docs/ui
# Expected: HTTP 200

# 3. No auth required for docs
curl -sf http://localhost:3000/api/docs | python3 -c "import json,sys; print('OK')"
# Expected: OK (no 401)

[strausmann]

Hi there! Just a friendly ping on this PR.

All 8 review comments from the initial review have been addressed in commit 2b429a8, and I've added comprehensive validation tests in ea0a3df (covering all 130+ endpoints).

Quick summary of what was fixed:

• Extended Session schema (email, displayName, avatar, provider, permissions)
• Added security: [] for public endpoints
• Corrected login response shape (requiresMfa + oneOf)
• Added /api/docs to PUBLIC_PATHS in hooks.server.ts
• Removed duplicate CSS loading in Swagger UI
• Fixed cookie name to dockhand_session

The PR is ready for re-review whenever you have a moment. Happy to make any further adjustments if needed!