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

src/routes/api/environments/[id]/+server.ts

@@ -18,6 +18,15 @@ import { closeEdgeConnection } from '$lib/server/hawser';
 import { computeAuditDiff } from '$lib/utils/diff';
 import { deleteEnvironmentIcon } from '$lib/server/env-icons';
 
+/**
+ * @openapi
+ * summary: Get a single environment by id, including its parsed labels and public IP
+ * path: id:integer! Environment id (from GET /api/environments)
+ * resp-200: {id:integer!, name:string!, connectionType:string!, labels:array<string>, publicIp:string}
+ * resp-403: Permission denied (RBAC 'environments:view' missing)
+ * resp-404: Environment not found
+ * resp-500: Unexpected error while loading the environment
+ */
 export const GET: RequestHandler = async ({ params, cookies }) => {
 	const auth = await authorize(cookies);
 	if (auth.authEnabled && !await auth.can('environments', 'view')) {
@@ -48,6 +57,19 @@ export const GET: RequestHandler = async ({ params, cookies }) => {
 	}
 };
 
+/**
+ * @openapi
+ * summary: Update an environment; renaming also renames its on-disk stacks/git-repos directories
+ * path: id:integer! Environment id (from GET /api/environments)
+ * body: {name:string, host:string, port:integer, protocol:string, tlsCa:string, tlsCert:string, tlsKey:string, tlsSkipVerify:boolean, icon:string, socketPath:string, collectActivity:boolean, collectMetrics:boolean, highlightChanges:boolean, labels:string, connectionType:string, hawserToken:string, publicIp:string}
+ * body-example: {"name":"hhdocker03","collectMetrics":true}
+ * resp-200: {id:integer!, name:string!, connectionType:string!, labels:array<string>, publicIp:string}
+ * resp-400: Invalid new name (rename validation)
+ * resp-403: Permission denied (RBAC 'environments:edit' missing)
+ * resp-404: Environment not found
+ * resp-409: Rename target directory already exists, or the on-disk rename failed (e.g. EXDEV across filesystems)
+ * resp-500: Unexpected error while updating the environment
+ */
 export const PUT: RequestHandler = async (event) => {
 	const { params, request, cookies } = event;
 	const auth = await authorize(cookies);
@@ -195,6 +217,16 @@ export const PUT: RequestHandler = async (event) => {
 	}
 };
 
+/**
+ * @openapi
+ * summary: Delete an environment and all its associated git stacks, schedules, icons, and on-disk directories
+ * path: id:integer! Environment id (from GET /api/environments)
+ * resp-200: {success:boolean!}
+ * resp-400: Invalid environment id, or the environment could not be deleted
+ * resp-403: Permission denied (RBAC 'environments:delete' missing)
+ * resp-404: Environment not found
+ * resp-500: Environment name is empty/whitespace (refuses to delete to avoid an unsafe directory cleanup), or an unexpected error
+ */
 export const DELETE: RequestHandler = async (event) => {
 	const { params, cookies } = event;
 	const auth = await authorize(cookies);