Skip to content

Commit 3f12f20

Browse files
SiumauricioSiumauricio
authored
Merge pull request #3139 from Dokploy/feat/sync-open-api-website-docs
Feat/sync open api website docs
2 parents 362416a + 4907a02 commit 3f12f20

File tree

6 files changed

+20212
-2
lines changed

6 files changed

+20212
-2
lines changed

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

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Generate and Sync OpenAPI
2+
3+
on:
4+
push:
5+
branches:
6+
- canary
7+
- main
8+
paths:
9+
- 'apps/dokploy/server/api/routers/**'
10+
- 'packages/server/src/services/**'
11+
- 'packages/server/src/db/schema/**'
12+
13+
workflow_dispatch:
14+
15+
jobs:
16+
generate-and-commit:
17+
name: Generate OpenAPI and commit to Dokploy repo
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: Checkout Dokploy repository
21+
uses: actions/checkout@v4
22+
with:
23+
token: ${{ secrets.GITHUB_TOKEN }}
24+
- uses: pnpm/action-setup@v4
25+
- uses: actions/setup-node@v4
26+
with:
27+
node-version: 20.16.0
28+
cache: "pnpm"
29+
30+
- name: Install dependencies
31+
run: pnpm install --frozen-lockfile
32+
33+
- name: Generate OpenAPI specification
34+
run: |
35+
pnpm generate:openapi
36+
37+
# Verifica que se generó correctamente
38+
if [ ! -f openapi.json ]; then
39+
echo "❌ openapi.json not found"
40+
exit 1
41+
fi
42+
43+
echo "✅ OpenAPI specification generated successfully"
44+
45+
- name: Sync to website repository
46+
run: |
47+
# Clona el repositorio de website
48+
git clone https://x-access-token:${{ secrets.DOCS_SYNC_TOKEN }}@github.com/dokploy/website.git website-repo
49+
50+
cd website-repo
51+
52+
# Copia el openapi.json al website (sobrescribe)
53+
mkdir -p public
54+
cp -f ../openapi.json apps/docs/public/openapi.json
55+
56+
# Configura git
57+
git config user.name "Dokploy Bot"
58+
git config user.email "[email protected]"
59+
60+
# Agrega y commitea siempre
61+
git add public/openapi.json
62+
git commit -m "chore: sync OpenAPI specification [skip ci]" \
63+
-m "Source: ${{ github.repository }}@${{ github.sha }}" \
64+
-m "Updated: $(date -u +'%Y-%m-%d %H:%M:%S UTC')" \
65+
--allow-empty
66+
67+
git push
68+
69+
echo "✅ OpenAPI synced to website successfully"
70+

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ node_modules
1313
.env.test.local
1414
.env.production.local
1515

16+
openapi.json
17+
1618
# Testing
1719
coverage
1820

‎apps/dokploy/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,8 @@
3434
"docker:build:canary": "./docker/build.sh canary",
3535
"docker:push:canary": "./docker/push.sh canary",
3636
"version": "echo $(node -p \"require('./package.json').version\")",
37-
"test": "vitest --config __test__/vitest.config.ts"
37+
"test": "vitest --config __test__/vitest.config.ts",
38+
"generate:openapi": "tsx -r dotenv/config scripts/generate-openapi.ts"
3839
},
3940
"dependencies": {
4041
"@ai-sdk/anthropic": "^2.0.5",

‎apps/dokploy/scripts/generate-openapi.ts‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
#!/usr/bin/env tsx
2+
3+
/**
4+
* Script to generate OpenAPI specification locally
5+
* This runs in CI/CD to generate the openapi.json file
6+
* which can then be consumed by the documentation website
7+
*/
8+
9+
import { writeFileSync } from "node:fs";
10+
import { dirname, resolve } from "node:path";
11+
import { fileURLToPath } from "node:url";
12+
import { generateOpenApiDocument } from "@dokploy/trpc-openapi";
13+
import { appRouter } from "../server/api/root";
14+
15+
const __filename = fileURLToPath(import.meta.url);
16+
const __dirname = dirname(__filename);
17+
18+
async function generateOpenAPI() {
19+
try {
20+
console.log("🔄 Generating OpenAPI specification...");
21+
22+
const openApiDocument = generateOpenApiDocument(appRouter, {
23+
title: "Dokploy API",
24+
version: "1.0.0",
25+
baseUrl: "https://your-dokploy-instance.com/api",
26+
docsUrl: "https://docs.dokploy.com/api",
27+
tags: [
28+
"admin",
29+
"docker",
30+
"compose",
31+
"registry",
32+
"cluster",
33+
"user",
34+
"domain",
35+
"destination",
36+
"backup",
37+
"deployment",
38+
"mounts",
39+
"certificates",
40+
"settings",
41+
"security",
42+
"redirects",
43+
"port",
44+
"project",
45+
"application",
46+
"mysql",
47+
"postgres",
48+
"redis",
49+
"mongo",
50+
"mariadb",
51+
"sshRouter",
52+
"gitProvider",
53+
"bitbucket",
54+
"github",
55+
"gitlab",
56+
"gitea",
57+
"server",
58+
"swarm",
59+
"ai",
60+
"organization",
61+
"schedule",
62+
"rollback",
63+
"volumeBackups",
64+
"environment",
65+
],
66+
});
67+
68+
// Enhance metadata
69+
openApiDocument.info = {
70+
title: "Dokploy API",
71+
description:
72+
"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.",
73+
version: "1.0.0",
74+
contact: {
75+
name: "Dokploy Team",
76+
url: "https://dokploy.com",
77+
},
78+
license: {
79+
name: "Apache 2.0",
80+
url: "https://github.com/dokploy/dokploy/blob/canary/LICENSE",
81+
},
82+
};
83+
84+
// Add security schemes
85+
openApiDocument.components = {
86+
...openApiDocument.components,
87+
securitySchemes: {
88+
apiKey: {
89+
type: "apiKey",
90+
in: "header",
91+
name: "x-api-key",
92+
description:
93+
"API key authentication. Generate an API key from your Dokploy dashboard under Settings > API Keys.",
94+
},
95+
},
96+
};
97+
98+
// Apply global security
99+
openApiDocument.security = [
100+
{
101+
apiKey: [],
102+
},
103+
];
104+
105+
// Add external docs
106+
openApiDocument.externalDocs = {
107+
description: "Full documentation",
108+
url: "https://docs.dokploy.com",
109+
};
110+
111+
// Write to root of repo
112+
const outputPath = resolve(__dirname, "../../../openapi.json");
113+
writeFileSync(
114+
outputPath,
115+
JSON.stringify(openApiDocument, null, 2),
116+
"utf-8",
117+
);
118+
119+
console.log("✅ OpenAPI specification generated successfully!");
120+
console.log(`📄 Output: ${outputPath}`);
121+
console.log(
122+
`📊 Endpoints: ${Object.keys(openApiDocument.paths || {}).length}`,
123+
);
124+
} catch (error) {
125+
console.error("❌ Error generating OpenAPI specification:", error);
126+
process.exit(1);
127+
} finally {
128+
process.exit(0);
129+
}
130+
}
131+
132+
generateOpenAPI();

0 commit comments

Comments
 (0)