feat: Add OpenAPI/Swagger documentation

backend/package.json

@@ -36,6 +36,8 @@
     "reflect-metadata": "^0.2.2",
     "sql.js": "^1.14.1",
     "sqlite3": "^5.1.7",
+    "swagger-jsdoc": "^6.3.0",
+    "swagger-ui-express": "^5.0.1",
     "uuid": "^9.0.1",
     "winston": "^3.14.2",
     "zod": "^3.22.0"
@@ -49,6 +51,8 @@
     "@types/jest": "^29.0.0",
     "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^20.0.0",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.8",
     "@types/uuid": "^9.0.7",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",

backend/scripts/generate-types.ts

@@ -0,0 +1,72 @@
+/**
+ * Generate TypeScript types from the OpenAPI specification.
+ *
+ * Usage:
+ *   npx ts-node scripts/generate-types.ts
+ *   # or via npm script:
+ *   pnpm --filter @chenaikit/backend run generate:api-types
+ *
+ * Output:
+ *   src/types/generated-api.ts
+ */
+
+import fs from "fs";
+import path from "path";
+
+async function main() {
+  // Dynamically import the swagger spec (it runs swagger-jsdoc at import time)
+  const { swaggerSpec } = await import("../src/config/swagger");
+
+  const specJson = JSON.stringify(swaggerSpec, null, 2);
+  const outputDir = path.resolve(__dirname, "..", "src", "types");
+  const specOutputPath = path.resolve(outputDir, "openapi-spec.json");
+
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Write the resolved OpenAPI spec as JSON
+  fs.writeFileSync(specOutputPath, specJson, "utf-8");
+  console.log(`✅ OpenAPI spec written to ${specOutputPath}`);
+
+  // Generate TypeScript types using openapi-typescript (if installed)
+  try {
+    const openapiTS = await import("openapi-typescript");
+    const generateFn = openapiTS.default || openapiTS;
+
+    if (typeof generateFn === "function") {
+      const output = await generateFn(swaggerSpec as any);
+      const tsOutputPath = path.resolve(outputDir, "generated-api.ts");
+      const content = typeof output === "string" ? output : String(output);
+      fs.writeFileSync(tsOutputPath, content, "utf-8");
+      console.log(`✅ TypeScript types written to ${tsOutputPath}`);
+    } else {
+      console.log(
+        "ℹ️  openapi-typescript loaded but generate function not found.",
+      );
+      console.log(
+        "   The OpenAPI spec JSON has been saved — you can generate types manually with:",
+      );
+      console.log(
+        `   npx openapi-typescript ${specOutputPath} -o ${path.resolve(outputDir, "generated-api.ts")}`,
+      );
+    }
+  } catch {
+    console.log(
+      "ℹ️  openapi-typescript not installed. Skipping TypeScript type generation.",
+    );
+    console.log(
+      "   Install it with: pnpm add -D openapi-typescript --filter @chenaikit/backend",
+    );
+    console.log("   Then re-run this script, or generate types manually with:");
+    console.log(
+      `   npx openapi-typescript ${specOutputPath} -o ${path.resolve(outputDir, "generated-api.ts")}`,
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error("Failed to generate types:", err);
+  process.exit(1);
+});