Skip to content

Commit aab982b

Browse files
author
Mauricio Siu
committed
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.
1 parent 362416a commit aab982b

5 files changed

Lines changed: 231 additions & 2 deletions

File tree

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

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
name: Generate and Sync OpenAPI
2+
3+
on:
4+
# Se ejecuta cuando hay cambios en los routers de la API
5+
push:
6+
branches:
7+
- canary
8+
paths:
9+
- 'apps/dokploy/server/api/routers/**'
10+
- 'packages/server/src/services/**'
11+
- 'packages/server/src/db/schema/**'
12+
13+
# Permite ejecución manual
14+
workflow_dispatch:
15+
16+
jobs:
17+
generate-and-commit:
18+
name: Generate OpenAPI and commit to Dokploy repo
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout Dokploy repository
22+
uses: actions/checkout@v4
23+
with:
24+
token: ${{ secrets.GITHUB_TOKEN }}
25+
26+
- name: Setup Node.js
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: '20'
30+
31+
- name: Setup pnpm
32+
uses: pnpm/action-setup@v2
33+
with:
34+
version: 8
35+
36+
- name: Install dependencies
37+
run: pnpm install --frozen-lockfile
38+
39+
- name: Generate OpenAPI specification
40+
run: pnpm generate:openapi
41+
42+
- name: Commit OpenAPI spec
43+
run: |
44+
git config user.name "Dokploy Bot"
45+
git config user.email "bot@dokploy.com"
46+
47+
# Verifica si el archivo existe
48+
if [ ! -f openapi.json ]; then
49+
echo "❌ openapi.json not found"
50+
exit 1
51+
fi
52+
53+
# Usa -f para forzar el add de archivos en .gitignore
54+
git add -f openapi.json
55+
56+
# Verifica si hay cambios para commitear
57+
if git diff --cached --quiet; then
58+
echo "📝 No changes detected in OpenAPI spec"
59+
echo "HAS_CHANGES=false" >> $GITHUB_ENV
60+
exit 0
61+
fi
62+
63+
echo "HAS_CHANGES=true" >> $GITHUB_ENV
64+
65+
# Commit los cambios
66+
git commit -m "chore: update OpenAPI specification [skip ci]
67+
68+
Generated from commit: ${{ github.sha }}
69+
Triggered by: ${{ github.event_name }}"
70+
71+
git push
72+
73+
echo "✅ OpenAPI spec committed successfully"
74+
75+
- name: Trigger website sync
76+
if: env.HAS_CHANGES == 'true'
77+
uses: peter-evans/repository-dispatch@v2
78+
with:
79+
token: ${{ secrets.DOCS_SYNC_TOKEN }}
80+
repository: dokploy/website # Cambia por tu repo de docs
81+
event-type: openapi-updated
82+
client-payload: '{"commit": "${{ github.sha }}", "timestamp": "${{ github.event.head_commit.timestamp }}"}'
83+
84+
- name: Create summary
85+
run: |
86+
echo "## 📊 OpenAPI Generation Summary" >> $GITHUB_STEP_SUMMARY
87+
echo "" >> $GITHUB_STEP_SUMMARY
88+
echo "- **Repository:** \`${{ github.repository }}\`" >> $GITHUB_STEP_SUMMARY
89+
echo "- **Commit:** \`${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
90+
echo "- **Trigger:** \`${{ github.event_name }}\`" >> $GITHUB_STEP_SUMMARY
91+
echo "- **Changes:** \`${{ env.HAS_CHANGES }}\`" >> $GITHUB_STEP_SUMMARY
92+
echo "- **Status:** ✅ Success" >> $GITHUB_STEP_SUMMARY
93+

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

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@
2020
"build": "pnpm -r run build",
2121
"format-and-lint": "biome check .",
2222
"check": "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true",
23-
"format-and-lint:fix": "biome check . --write"
23+
"format-and-lint:fix": "biome check . --write",
24+
"generate:openapi": "pnpm --filter=dokploy run generate:openapi"
2425
},
2526
"devDependencies": {
2627
"@biomejs/biome": "2.1.1",

0 commit comments

Comments
 (0)