Merge pull request #3139 from Dokploy/feat/sync-open-api-website-docs

Feat/sync open api website docs

.github/workflows/sync-openapi-docs.yml

@@ -0,0 +1,70 @@
+name: Generate and Sync OpenAPI
+
+on:
+  push:
+    branches:
+      - canary
+      - main
+    paths:
+      - 'apps/dokploy/server/api/routers/**'
+      - 'packages/server/src/services/**'
+      - 'packages/server/src/db/schema/**'
+
+  workflow_dispatch:
+
+jobs:
+  generate-and-commit:
+    name: Generate OpenAPI and commit to Dokploy repo
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Dokploy repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.16.0
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate OpenAPI specification
+        run: |
+          pnpm generate:openapi
+          
+          # Verifica que se generó correctamente
+          if [ ! -f openapi.json ]; then
+            echo "❌ openapi.json not found"
+            exit 1
+          fi
+          
+          echo "✅ OpenAPI specification generated successfully"
+
+      - name: Sync to website repository
+        run: |
+          # Clona el repositorio de website
+          git clone https://x-access-token:${{ secrets.DOCS_SYNC_TOKEN }}@github.com/dokploy/website.git website-repo
+          
+          cd website-repo
+          
+          # Copia el openapi.json al website (sobrescribe)
+          mkdir -p public
+          cp -f ../openapi.json apps/docs/public/openapi.json
+          
+          # Configura git
+          git config user.name "Dokploy Bot"
+          git config user.email "bot@dokploy.com"
+          
+          # Agrega y commitea siempre
+          git add public/openapi.json
+          git commit -m "chore: sync OpenAPI specification [skip ci]" \
+            -m "Source: ${{ github.repository }}@${{ github.sha }}" \
+            -m "Updated: $(date -u +'%Y-%m-%d %H:%M:%S UTC')" \
+            --allow-empty
+          
+          git push
+          
+          echo "✅ OpenAPI synced to website successfully"
+

.gitignore

@@ -13,6 +13,8 @@ node_modules
 .env.test.local
 .env.production.local
 
+openapi.json
+
 # Testing
 coverage
 

apps/dokploy/package.json

@@ -34,7 +34,8 @@
 		"docker:build:canary": "./docker/build.sh canary",
 		"docker:push:canary": "./docker/push.sh canary",
 		"version": "echo $(node -p \"require('./package.json').version\")",
-		"test": "vitest --config __test__/vitest.config.ts"
+		"test": "vitest --config __test__/vitest.config.ts",
+		"generate:openapi": "tsx -r dotenv/config scripts/generate-openapi.ts"
 	},
 	"dependencies": {
 		"@ai-sdk/anthropic": "^2.0.5",

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();

package.json

@@ -20,7 +20,8 @@
 		"build": "pnpm -r run build",
 		"format-and-lint": "biome check .",
 		"check": "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true",
-		"format-and-lint:fix": "biome check . --write"
+		"format-and-lint:fix": "biome check . --write",
+		"generate:openapi": "pnpm --filter=dokploy run generate:openapi"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.1.1",