OpenAPI spec at /api/docs with a Scalar viewer, opt-in via FEAT_API_DOCS

src/routes/api/backup/restore/+server.ts

@@ -8,6 +8,18 @@ import { createJobResponse } from '$lib/server/sse';
 import { auditRestore } from '$lib/server/audit';
 import { guardSnapshotEnvAccess } from '$lib/server/backups/route-guards';
 
+/**
+ * POST /api/backup/restore - Restore a snapshot (streamed job)
+ *
+ * @openapi
+ * summary: Restore a backup snapshot in-place or to a new location, streaming progress as a Server-Sent Events job
+ * description: Returns a text/event-stream that emits `progress` events and a final `result` event. An in-place restore is destructive and requires confirmOverwrite:true. Authorization and snapshot-environment access are checked before the request shape is validated. destinationId from GET /api/backup/destinations. snapshotId from GET /api/backup/snapshots. environmentId from GET /api/environments.
+ * body: {destinationId:integer!, snapshotId:string!, mode:string, targetType:string, volumes:array<string>, environmentId:integer, confirmOverwrite:boolean, targetPath:string, targetName:string, postRestore:string, volumeDestinations:array<{}>}
+ * body-example: {"destinationId":3,"snapshotId":"a1b2c3d4","mode":"new-location","targetType":"container","targetName":"nextcloud-restored","environmentId":1,"confirmOverwrite":false}
+ * resp-200: Server-Sent Events stream of progress and a final result event (status "success" or "error")
+ * resp-400: Invalid restore request; the response "issues" array lists the validation problems
+ * resp-403: Permission denied — requires "backups:manage", or no access to the target or snapshot-owning environment
+ */
 export const POST: RequestHandler = async (event) => {
 	const { request, cookies } = event;
 	const auth = await authorize(cookies);