feat: Adds auto openapi doc generation + swagger UI for API

.changeset/moody-guests-smell.md

@@ -0,0 +1,5 @@
+---
+"@hyperdx/api": patch
+---
+
+Adds openapidoc annotations for spec generation and swagger route for development

.gitignore

@@ -35,6 +35,9 @@ packages/app/.vercel
 packages/app/coverage
 packages/app/out
 
+# OpenAPI spec
+packages/public/openapi.json
+
 # optional npm cache directory
 **/.npm
 

packages/api/.env.development

@@ -18,3 +18,4 @@ PORT=${HYPERDX_API_PORT}
 REDIS_URL=redis://localhost:6379
 USAGE_STATS_ENABLED=false
 NODE_OPTIONS="--max-http-header-size=131072"
+ENABLE_SWAGGER=true

packages/api/package.json

@@ -73,12 +73,15 @@
     "@types/semver": "^7.3.12",
     "@types/sqlstring": "^2.3.0",
     "@types/supertest": "^2.0.12",
+    "@types/swagger-jsdoc": "^6",
     "@types/uuid": "^8.3.4",
     "jest": "^28.1.3",
     "migrate-mongo": "^11.0.0",
     "nodemon": "^2.0.20",
     "rimraf": "^4.4.1",
     "supertest": "^6.3.1",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
     "ts-jest": "^28.0.5",
     "ts-node": "^10.8.1",
     "tsc-alias": "^1.8.8",
@@ -98,6 +101,7 @@
     "dev:migrate-db-create": "ts-node node_modules/.bin/migrate-mongo create -f migrate-mongo-config.ts",
     "dev:migrate-db": "ts-node node_modules/.bin/migrate-mongo up -f migrate-mongo-config.ts",
     "dev:migrate-ch-create": "migrate create -ext sql -dir ./migrations/ch -seq",
-    "dev:migrate-ch": "migrate -database 'clickhouse://localhost:9000?database=default&x-multi-statement=true' -path ./migrations/ch up"
+    "dev:migrate-ch": "migrate -database 'clickhouse://localhost:9000?database=default&x-multi-statement=true' -path ./migrations/ch up",
+    "docgen": "ts-node scripts/generate-api-docs.ts"
   }
 }

packages/api/scripts/generate-api-docs.ts

@@ -0,0 +1,12 @@
+import fs from 'fs';
+import path from 'path';
+import swaggerJsdoc from 'swagger-jsdoc';
+
+import { swaggerOptions } from '../src/utils/swagger';
+
+const specs = swaggerJsdoc(swaggerOptions);
+const outputPath = path.resolve(__dirname, '../../public/openapi.json');
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, JSON.stringify(specs, null, 2));
+
+console.log(`OpenAPI specification written to ${outputPath}`);

packages/api/src/api-app.ts

@@ -18,6 +18,7 @@ import externalRoutersV2 from './routers/external-api/v2';
 import usageStats from './tasks/usageStats';
 import { expressLogger } from './utils/logger';
 import passport from './utils/passport';
+import { setupSwagger } from './utils/swagger';
 
 const app: express.Application = express();
 
@@ -102,7 +103,15 @@ app.use('/clickhouse-proxy', isUserAuthenticated, clickhouseProxyRouter);
 // ---------------------------------------------------------------------
 // ----------------------- External Routers ----------------------------
 // ---------------------------------------------------------------------
-// API v1
+// API v2
+// Only initialize Swagger in development or if explicitly enabled
+if (
+  process.env.NODE_ENV !== 'production' ||
+  process.env.ENABLE_SWAGGER === 'true'
+) {
+  setupSwagger(app);
+}
+
 app.use('/api/v2', externalRoutersV2);
 
 // error handling