feat: add OpenAPI generation script and workflow

- Introduced a new script to generate OpenAPI specifications for the Dokploy API. - Added a GitHub Actions workflow to automate the generation and syncing of OpenAPI documentation upon changes in the API routers. - Updated package.json files to include new commands for generating OpenAPI specifications. - Added openapi.json to .gitignore to prevent accidental commits of generated files.
2026-06-29 19:15:22 +02:00 · 2025-11-30 00:30:40 -06:00
parent 362416afa8
commit aab982b431
5 changed files with 231 additions and 2 deletions
--- a/apps/dokploy/scripts/generate-openapi.ts
+++ b/apps/dokploy/scripts/generate-openapi.ts
@@ -0,0 +1,132 @@
+#!/usr/bin/env tsx
+
+/**
+ * Script to generate OpenAPI specification locally
+ * This runs in CI/CD to generate the openapi.json file
+ * which can then be consumed by the documentation website
+ */
+
+import { writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateOpenApiDocument } from "@dokploy/trpc-openapi";
+import { appRouter } from "../server/api/root";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function generateOpenAPI() {
+	try {
+		console.log("🔄 Generating OpenAPI specification...");
+
+		const openApiDocument = generateOpenApiDocument(appRouter, {
+			title: "Dokploy API",
+			version: "1.0.0",
+			baseUrl: "https://your-dokploy-instance.com/api",
+			docsUrl: "https://docs.dokploy.com/api",
+			tags: [
+				"admin",
+				"docker",
+				"compose",
+				"registry",
+				"cluster",
+				"user",
+				"domain",
+				"destination",
+				"backup",
+				"deployment",
+				"mounts",
+				"certificates",
+				"settings",
+				"security",
+				"redirects",
+				"port",
+				"project",
+				"application",
+				"mysql",
+				"postgres",
+				"redis",
+				"mongo",
+				"mariadb",
+				"sshRouter",
+				"gitProvider",
+				"bitbucket",
+				"github",
+				"gitlab",
+				"gitea",
+				"server",
+				"swarm",
+				"ai",
+				"organization",
+				"schedule",
+				"rollback",
+				"volumeBackups",
+				"environment",
+			],
+		});
+
+		// Enhance metadata
+		openApiDocument.info = {
+			title: "Dokploy API",
+			description:
+				"Complete API documentation for Dokploy - Deploy applications, manage databases, and orchestrate your infrastructure. This API allows you to programmatically manage all aspects of your Dokploy instance.",
+			version: "1.0.0",
+			contact: {
+				name: "Dokploy Team",
+				url: "https://dokploy.com",
+			},
+			license: {
+				name: "Apache 2.0",
+				url: "https://github.com/dokploy/dokploy/blob/canary/LICENSE",
+			},
+		};
+
+		// Add security schemes
+		openApiDocument.components = {
+			...openApiDocument.components,
+			securitySchemes: {
+				apiKey: {
+					type: "apiKey",
+					in: "header",
+					name: "x-api-key",
+					description:
+						"API key authentication. Generate an API key from your Dokploy dashboard under Settings > API Keys.",
+				},
+			},
+		};
+
+		// Apply global security
+		openApiDocument.security = [
+			{
+				apiKey: [],
+			},
+		];
+
+		// Add external docs
+		openApiDocument.externalDocs = {
+			description: "Full documentation",
+			url: "https://docs.dokploy.com",
+		};
+
+		// Write to root of repo
+		const outputPath = resolve(__dirname, "../../../openapi.json");
+		writeFileSync(
+			outputPath,
+			JSON.stringify(openApiDocument, null, 2),
+			"utf-8",
+		);
+
+		console.log("✅ OpenAPI specification generated successfully!");
+		console.log(`📄 Output: ${outputPath}`);
+		console.log(
+			`📊 Endpoints: ${Object.keys(openApiDocument.paths || {}).length}`,
+		);
+	} catch (error) {
+		console.error("❌ Error generating OpenAPI specification:", error);
+		process.exit(1);
+	} finally {
+		process.exit(0);
+	}
+}
+
+generateOpenAPI();