OpenAPI spec at /api/docs with a Scalar viewer, opt-in via FEAT_API_DOCS
This commit is contained in:
251 files changed
+32497
-66
No files matched your search
@@ -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
@@ -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
@@ -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
@@ -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);
|
||||
|
||||
Reference in new issue
Block a user