Self-hosted, plugin-based server management.
TypeScript dockerhomelabpluginsrdpremote-desktopself-hostedserver-managementsftpsshterminaltermixvnc
/**
* Builds an OpenAPI spec from the @openapi JSDoc blocks above routes. Core and
* every plugin use this, so the docs site renders them all the same way.
*/
import swaggerJSDoc from "@deadendjs/swagger-jsdoc";
export interface OpenApiTag {
name: string;
description?: string;
}
export interface BuildOpenApiOptions {
title: string;
version: string;
description?: string;
/** Source files or globs holding @openapi blocks. */
files: string[];
tags?: OpenApiTag[];
}
export type OpenApiSpec = Record<string, unknown> & {
paths?: Record<string, unknown>;
};
/** How every Termix route is signed in to. */
export const TERMIX_SECURITY_SCHEMES = {
bearerAuth: {
type: "http",
scheme: "bearer",
bearerFormat: "JWT",
description:
"Session token sent in the Authorization header as Bearer and the token.",
},
cookieAuth: {
type: "apiKey",
in: "cookie",
name: "jwt",
description:
"Session JWT cookie set at sign-in. When present, it takes precedence over the Authorization header.",
},
apiKeyAuth: {
type: "http",
scheme: "bearer",
bearerFormat: "API key starting with tmx_",
description:
"API key sent in the Authorization header as Bearer and the key, which starts with tmx_. It acts as the key owner and cannot act as anyone else.",
},
} as const;
export async function buildOpenApi(
options: BuildOpenApiOptions,
): Promise<OpenApiSpec> {
const spec = (await swaggerJSDoc({
definition: {
openapi: "3.0.3",
info: {
title: options.title,
version: options.version,
...(options.description ? { description: options.description } : {}),
},
servers: [{ url: "/", description: "Your Termix server" }],
components: {
securitySchemes: TERMIX_SECURITY_SCHEMES,
schemas: {
Error: {
type: "object",
properties: {
error: { type: "string" },
details: { type: "string" },
},
},
},
},
security: [{ bearerAuth: [] }, { cookieAuth: [] }, { apiKeyAuth: [] }],
...(options.tags?.length ? { tags: options.tags } : {}),
},
apis: options.files.map((f) => f.replace(/\\/g, "/")),
failOnErrors: true,
} as Parameters<typeof swaggerJSDoc>[0])) as OpenApiSpec;
return spec;
}
/** Whether a spec documents any route. */
export function hasOpenApiPaths(spec: OpenApiSpec): boolean {
return Object.keys(spec.paths ?? {}).length > 0;
}