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

This commit is contained in:
jarek committed 2026-08-17 09:50:34 +02:00
1 parent ba8670af66
commit da26f7f764
251 files changed
+32497 -66

No files matched your search

+15
View File
@@ -4,6 +4,21 @@ import { authorize } from '$lib/server/authorize';
import { auditStack } from '$lib/server/audit';
import type { RequestHandler } from './$types';
/**
* @openapi
* summary: Remove a stack completely (compose down + delete files + database cleanup)
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment id (from GET /api/environments)
* query: force:boolean Force removal even if the compose down step fails
* query: volumes:boolean Also remove named volumes (docker compose down --volumes)
* query: files:boolean Delete the stack's on-disk files/directory too (default true; pass files=false to keep them on disk)
* resp-200: {success:boolean!}
* resp-200-example: {"success":true}
* resp-400: Compose down failed and force was not set
* resp-403: Permission denied, or access denied to this environment
* resp-404: Compose file not found for this stack
* resp-500: Unexpected error while removing the stack
*/
export const DELETE: RequestHandler = async (event) => {
const { params, url, cookies } = event;
const auth = await authorize(cookies);
@@ -9,8 +9,16 @@ import { join, dirname } from 'node:path';
/**
* POST /api/stacks/[name]/check-path-change
*
* Check if the proposed compose path differs from current and if old directory has files.
* Returns information about what would need to be moved if location changes.
* @openapi
* summary: Check whether a proposed compose path moves the stack to a different directory and how many files the old directory still holds
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment ID the stack belongs to (from GET /api/environments)
* body: {newComposePath:string!}
* body-example: {"newComposePath":"/opt/stacks/web/compose.yaml"}
* resp-200: {hasChanges:boolean!, oldDir:string, newDir:string, fileCount:integer!, currentComposePath:string}
* resp-200-example: {"hasChanges":true,"oldDir":"/opt/stacks/old","newDir":"/opt/stacks/web","fileCount":3,"currentComposePath":"/opt/stacks/old/compose.yaml"}
* resp-403: Permission denied (requires stacks:edit)
* resp-500: Failed to check path changes
*/
export const POST: RequestHandler = async ({ params, request, url, cookies }) => {
const auth = await authorize(cookies);
@@ -5,6 +5,15 @@ import { authorize } from '$lib/server/authorize';
import { createJobResponse } from '$lib/server/sse';
// GET /api/stacks/[name]/compose - Get compose file content
/**
* @openapi
* summary: Get a stack's compose file content plus its resolved compose/env paths
* path: name:string The stack name
* query: env:integer Environment id the stack belongs to
* resp-403: Permission denied (needs stacks:view)
* resp-404: Stack or compose file not found
* resp-500: Failed to read the compose file
*/
export const GET: RequestHandler = async ({ params, url, cookies }) => {
const auth = await authorize(cookies);
if (auth.authEnabled && !(await auth.can('stacks', 'view'))) {
@@ -42,6 +51,17 @@ export const GET: RequestHandler = async ({ params, url, cookies }) => {
};
// PUT /api/stacks/[name]/compose - Update compose file content
/**
* @openapi
* summary: Save a stack's compose file (and optionally relocate it, bind a secret provider, and redeploy)
* description: Every accepted PUT persists the compose content; with restart it also redeploys. Supports moving the compose/env to a new path and binding a secret provider.
* path: name:string The stack name
* query: env:integer Environment id the stack belongs to
* body: {content:string!, composePath:string, envPath:string, oldComposePath:string, oldEnvPath:string, moveFromDir:string, restart:boolean, secretProviderId:integer}
* resp-400: Invalid request (e.g. missing content, or secretProviderId wrong type)
* resp-403: Permission denied (needs stacks:edit; binding a secret provider also needs secrets:view)
* resp-500: Failed to save or deploy the compose file
*/
export const PUT: RequestHandler = async ({ params, request, url, cookies }) => {
const auth = await authorize(cookies);
@@ -6,6 +6,16 @@ import { authorize } from '$lib/server/authorize';
// GET /api/stacks/[name]/delete-preview?env=N
// Returns the on-disk directories a delete-with-files would remove, so the confirm modal
// shows the user EXACTLY what the backend will delete (same source of truth — no drift).
/**
* @openapi
* summary: Preview the on-disk directories and named volumes a delete-with-files would remove for a stack
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment ID the stack belongs to (from GET /api/environments)
* resp-200: {stackName:string!, sourceType:string, stackDir:string, gitDir:string, namedVolumes:array<string>!, canDeleteFiles:boolean!}
* resp-200-example: {"stackName":"web","sourceType":"internal","stackDir":"/opt/stacks/web","gitDir":null,"namedVolumes":["web_data"],"canDeleteFiles":true}
* resp-403: Permission denied (requires stacks:remove)
* resp-500: Failed to compute the deletion preview
*/
export const GET: RequestHandler = async ({ params, url, cookies }) => {
const auth = await authorize(cookies);
const envId = url.searchParams.get('env');
@@ -5,6 +5,16 @@ import { auditStack } from '$lib/server/audit';
import { createJobResponse } from '$lib/server/sse';
import type { RequestHandler } from './$types';
/**
* @openapi
* summary: Deploy (docker compose up) a stack, optionally pulling images, building, and force-recreating; progress and the final result stream over Server-Sent Events
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment ID the stack belongs to (from GET /api/environments)
* body: {pull:boolean, build:boolean, forceRecreate:boolean}
* body-example: {"pull":true,"build":false,"forceRecreate":false}
* resp-200: Server-Sent-Events job stream with progress events and a final result event ({success, output})
* resp-403: Permission denied (requires stacks:start, or environment access denied on enterprise)
*/
export const POST: RequestHandler = async (event) => {
const { params, url, cookies, request } = event;
const auth = await authorize(cookies);
@@ -5,6 +5,18 @@ import { auditStack } from '$lib/server/audit';
import { createJobResponse } from '$lib/server/sse';
import type { RequestHandler } from './$types';
/**
* @openapi
* summary: Take a stack down (docker compose down — removes containers, keeps files), asynchronously
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment id (from GET /api/environments)
* body: {removeVolumes:boolean}
* body-example: {"removeVolumes":false}
* resp-200: {jobId:string!}
* resp-200-desc: Fire-and-forget job id — poll GET /api/jobs/{jobId} for the result. Send "Accept: application/json" (without text/event-stream) to instead block and receive the final {success,output|error} synchronously.
* resp-200-example: {"jobId":"3f9c5b1a-2e4d-4a6f-9b0a-1c7d8e9f0a1b"}
* resp-403: Permission denied, or access denied to this environment
*/
export const POST: RequestHandler = async (event) => {
const { params, url, cookies, request } = event;
const auth = await authorize(cookies);
+19
View File
@@ -34,6 +34,15 @@ function parseEnvFile(content: string): Record<string, string> {
* Secrets are stored only in the database and injected via shell environment at runtime.
* The .env file only contains non-secret variables.
*/
/**
* @openapi
* summary: Get a stack's env vars (non-secrets from file, secrets masked from DB) plus injected provider keys
* path: name:string The stack name
* query: env:integer Environment id the stack belongs to
* resp-200: {variables:array<object>!, injectedSecretKeys:array<string>, secretProvider:object}
* resp-403: Permission denied (needs stacks:view)
* resp-500: Failed to read env vars
*/
export const GET: RequestHandler = async ({ params, url, cookies }) => {
const auth = await authorize(cookies);
const envId = url.searchParams.get('env');
@@ -134,6 +143,16 @@ export const GET: RequestHandler = async ({ params, url, cookies }) => {
* If a secret's value is '***' (masked placeholder), the original value
* from the database is preserved.
*/
/**
* @openapi
* summary: Save a stack's secret env vars to the DB (secrets never hit disk)
* path: name:string The stack name
* query: env:integer Environment id the stack belongs to
* body: {variables:array<object>!}
* resp-400: Invalid variables payload
* resp-403: Permission denied (needs stacks:edit)
* resp-500: Failed to save env vars
*/
export const PUT: RequestHandler = async ({ params, url, cookies, request }) => {
const auth = await authorize(cookies);
const envId = url.searchParams.get('env');
+21 -3
View File
@@ -8,7 +8,15 @@ import type { RequestHandler } from './$types';
/**
* GET /api/stacks/[name]/env/raw?env=X
* Get the raw .env file content as-is (with comments, formatting, etc.)
*
* @openapi
* summary: Get the raw .env file content as-is (comments and formatting preserved) for a stack
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment ID the stack belongs to (from GET /api/environments)
* resp-200: {content:string!, noEnvFile:boolean}
* resp-200-example: {"content":"FOO=bar\n# comment\nBAZ=qux\n"}
* resp-403: Permission denied (requires stacks:view, or environment access denied on enterprise)
* resp-500: Failed to get environment file
*/
export const GET: RequestHandler = async ({ params, url, cookies }) => {
const auth = await authorize(cookies);
@@ -73,8 +81,18 @@ export const GET: RequestHandler = async ({ params, url, cookies }) => {
/**
* PUT /api/stacks/[name]/env/raw?env=X
* Save raw .env file content directly to disk.
* Body: { content: string }
*
* @openapi
* summary: Write raw .env file content to disk for a stack; empty content deletes the .env file, and masked "***" placeholders are rejected to avoid corrupting secrets
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment ID the stack belongs to (from GET /api/environments)
* body: {content:string!}
* body-example: {"content":"FOO=bar\nBAZ=qux\n"}
* resp-200: {success:boolean!, noEnvFile:boolean, deleted:boolean}
* resp-200-example: {"success":true}
* resp-400: Invalid body (content string required) or refusal to write a masked "***" placeholder
* resp-403: Permission denied (requires stacks:edit, or environment access denied on enterprise)
* resp-500: Failed to save environment file
*/
export const PUT: RequestHandler = async ({ params, url, cookies, request }) => {
const auth = await authorize(cookies);
+12 -3
View File
@@ -91,9 +91,18 @@ function extractComposeVars(yaml: string): { required: string[]; optional: strin
/**
* POST /api/stacks/[name]/env/validate?env=X
* Validate stack environment variables against compose file requirements.
* Can use saved compose file or accept compose content in body.
* Body (optional): { compose: "yaml content..." }
*
* @openapi
* summary: Validate a stack's defined environment variables against the variables required/optional by its compose file (compose content and the defined variable list may be supplied in the body, otherwise loaded from the saved file/DB)
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment ID the stack belongs to (from GET /api/environments)
* body: {compose:string, variables:array<string>}
* body-example: {"compose":"services:\n web:\n image: ${IMAGE}","variables":["IMAGE"]}
* resp-200: {valid:boolean!, required:array<string>!, optional:array<string>!, defined:array<string>!, missing:array<string>!, unused:array<string>!}
* resp-200-example: {"valid":false,"required":["IMAGE"],"optional":[],"defined":[],"missing":["IMAGE"],"unused":[]}
* resp-400: No compose content provided and no saved compose file found
* resp-403: Permission denied (requires stacks:view, or environment access denied on enterprise)
* resp-500: Failed to validate environment variables
*/
export const POST: RequestHandler = async ({ params, url, cookies, request }) => {
const auth = await authorize(cookies);
@@ -8,8 +8,17 @@ import { join, dirname } from 'node:path';
/**
* POST /api/stacks/[name]/relocate
*
* Move all stack files from old directory to new location.
* Updates the database with new paths and returns refreshed content.
* @openapi
* summary: Move all stack files from the old directory to a new location, update the stored compose/env paths, and return the refreshed compose/env content
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment ID the stack belongs to (from GET /api/environments)
* body: {oldDir:string!, newComposePath:string!, newEnvPath:string}
* body-example: {"oldDir":"/opt/stacks/old","newComposePath":"/opt/stacks/web/compose.yaml","newEnvPath":"/opt/stacks/web/.env"}
* resp-200: {success:boolean!, movedFiles:array<string>!, errors:array<string>, composeContent:string!, rawEnvContent:string!, envVars:array<{key:string!, value:string!, isSecret:boolean!}>!}
* resp-200-example: {"success":true,"movedFiles":["compose.yaml",".env"],"composeContent":"services: {}","rawEnvContent":"FOO=bar\n","envVars":[{"key":"FOO","value":"bar","isSecret":false}]}
* resp-400: oldDir and newComposePath are required, or the source directory does not exist
* resp-403: Permission denied (requires stacks:edit)
* resp-500: Failed to relocate stack
*/
export const POST: RequestHandler = async ({ params, request, url, cookies }) => {
const auth = await authorize(cookies);
@@ -5,6 +5,15 @@ import { auditStack } from '$lib/server/audit';
import { createJobResponse } from '$lib/server/sse';
import type { RequestHandler } from './$types';
/**
* @openapi
* summary: Restart a stack (mode=restart) or recreate its containers (mode=recreate); progress and the final result stream over Server-Sent Events
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment ID the stack belongs to (from GET /api/environments)
* query: mode:string Restart mode — "recreate" recreates containers, anything else performs a plain restart
* resp-200: Server-Sent-Events job stream with a final result event ({success, output})
* resp-403: Permission denied (requires stacks:restart, or environment access denied on enterprise)
*/
export const POST: RequestHandler = async (event) => {
const { params, url, cookies } = event;
const auth = await authorize(cookies);
@@ -5,6 +5,16 @@ import { auditStack } from '$lib/server/audit';
import { createJobResponse } from '$lib/server/sse';
import type { RequestHandler } from './$types';
/**
* @openapi
* summary: Start a stack (docker compose start/up), asynchronously
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment id (from GET /api/environments)
* resp-200: {jobId:string!}
* resp-200-desc: Fire-and-forget job id — poll GET /api/jobs/{jobId} for the result. Send "Accept: application/json" (without text/event-stream) to instead block and receive the final {success,output|error} synchronously.
* resp-200-example: {"jobId":"3f9c5b1a-2e4d-4a6f-9b0a-1c7d8e9f0a1b"}
* resp-403: Permission denied, or access denied to this environment
*/
export const POST: RequestHandler = async (event) => {
const { params, url, cookies } = event;
const auth = await authorize(cookies);
@@ -5,6 +5,16 @@ import { auditStack } from '$lib/server/audit';
import { createJobResponse } from '$lib/server/sse';
import type { RequestHandler } from './$types';
/**
* @openapi
* summary: Stop a stack (docker compose stop), asynchronously
* path: name:string! Stack name (from GET /api/stacks)
* query: env:integer Environment id (from GET /api/environments)
* resp-200: {jobId:string!}
* resp-200-desc: Fire-and-forget job id — poll GET /api/jobs/{jobId} for the result. Send "Accept: application/json" (without text/event-stream) to instead block and receive the final {success,output|error} synchronously.
* resp-200-example: {"jobId":"3f9c5b1a-2e4d-4a6f-9b0a-1c7d8e9f0a1b"}
* resp-403: Permission denied, or access denied to this environment
*/
export const POST: RequestHandler = async (event) => {
const { params, url, cookies } = event;
const auth = await authorize(cookies);