Add Swagger UI API documentation

Author: Rajat

bun.lock

@@ -24,6 +24,9 @@ The API listens on `http://127.0.0.1:4000`. `SEED=1` in the example environment
 creates local demo users, tenants, credentials, notes, and billing data. Do
 not enable it for a production deployment.
 
+Open `http://127.0.0.1:4000/docs` for the interactive Swagger UI, or fetch the
+generated OpenAPI document from `http://127.0.0.1:4000/openapi.json`.
+
 In a second terminal, start the Next.js web app:
 
 ```bash

examples/reference-product/README.md

@@ -40,12 +40,14 @@
     "express": "^4.21.2",
     "pg": "^8.23.0",
     "pino": "^9.6.0",
+    "swagger-ui-express": "^5.0.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.2.17",
     "@types/express": "^4.17.21",
     "@types/node": "^22.14.1",
+    "@types/swagger-ui-express": "^4.1.8",
     "drizzle-kit": "0.31.4",
     "typescript": "^5.9.3",
     "@types/bun": "^1.4.1"

examples/reference-product/apps/api/package.json

@@ -473,6 +473,15 @@ describe.serial("reference API adapters", () => {
     const openapi = await fetch(`http://127.0.0.1:${address.port}/openapi.json`);
     expect(openapi.status).toBe(200);
     expect((await openapi.json()).paths["/v1/notes"]).toBeDefined();
+    const docs = await fetch(`http://127.0.0.1:${address.port}/docs`);
+    expect(docs.status).toBe(200);
+    expect(docs.headers.get("content-type")).toContain("text/html");
+    expect(await docs.text()).toContain("Swagger UI");
+    const docsInitializer = await fetch(
+      `http://127.0.0.1:${address.port}/docs/swagger-ui-init.js`,
+    );
+    expect(docsInitializer.status).toBe(200);
+    expect(await docsInitializer.text()).toContain('"/v1/notes"');
     const protectedResource = await fetch(
       `http://127.0.0.1:${address.port}/.well-known/oauth-protected-resource/mcp`,
     );

examples/reference-product/apps/api/src/app.test.ts

@@ -4,10 +4,12 @@ import { readOrCreateRequestId } from "@codelitdev/platform";
 import { contract } from "@reference-product/api-contract";
 import { createExpressEndpoints, initServer } from "@ts-rest/express";
 import { toNodeHandler } from "better-auth/node";
-import express, { type Express } from "express";
+import express, { type Express, type RequestHandler } from "express";
+import swaggerUi from "swagger-ui-express";
 import { AUTH_BASE_PATH, MCP_SCOPES_SUPPORTED } from "./auth/options.js";
 import type { DispatchDeps } from "./deps.js";
 import { dispatch } from "./dispatch.js";
+import { createOpenApiDocument } from "./openapi.js";
 
 export function createExpressApp(deps: DispatchDeps): Express {
   const app = express();
@@ -64,6 +66,21 @@ export function createExpressApp(deps: DispatchDeps): Express {
       loginMethods: [{ type: "email-otp" }],
     }),
   );
+  // The Swagger typings can resolve a separate Express type version in a
+  // freshly generated workspace, so normalize its handlers at this boundary.
+  app.use(
+    "/docs",
+    ...(swaggerUi.serve as unknown as RequestHandler[]),
+    swaggerUi.setup(createOpenApiDocument(deps.auth.publicApiUrl), {
+      explorer: true,
+      swaggerOptions: {
+        persistAuthorization: true,
+        displayRequestDuration: true,
+        docExpansion: "none",
+        defaultModelsExpandDepth: -1,
+      },
+    }) as unknown as RequestHandler,
+  );
   app.use(express.json({ limit: "32kb" }));
 
   const server = initServer();

examples/reference-product/apps/api/src/express-app.ts

@@ -1,3 +1,6 @@
 # __PRODUCT_NAME__ API
 
 Product-owned application services live here.
+
+Open the interactive Swagger UI at `GET /docs`, or fetch the generated OpenAPI
+document directly from `GET /openapi.json`.

templates/saas-product/apps/api/README.md

@@ -40,12 +40,14 @@
     "express": "^4.21.2",
     "pg": "^8.23.0",
     "pino": "^9.6.0",
+    "swagger-ui-express": "^5.0.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.2.17",
     "@types/express": "^4.17.21",
     "@types/node": "^22.14.1",
+    "@types/swagger-ui-express": "^4.1.8",
     "drizzle-kit": "0.31.4",
     "typescript": "^5.9.3",
     "@types/bun": "^1.4.1"

templates/saas-product/apps/api/package.json

@@ -473,6 +473,15 @@ describe.serial("reference API adapters", () => {
     const openapi = await fetch(`http://127.0.0.1:${address.port}/openapi.json`);
     expect(openapi.status).toBe(200);
     expect((await openapi.json()).paths["/v1/notes"]).toBeDefined();
+    const docs = await fetch(`http://127.0.0.1:${address.port}/docs`);
+    expect(docs.status).toBe(200);
+    expect(docs.headers.get("content-type")).toContain("text/html");
+    expect(await docs.text()).toContain("Swagger UI");
+    const docsInitializer = await fetch(
+      `http://127.0.0.1:${address.port}/docs/swagger-ui-init.js`,
+    );
+    expect(docsInitializer.status).toBe(200);
+    expect(await docsInitializer.text()).toContain('"/v1/notes"');
     const protectedResource = await fetch(
       `http://127.0.0.1:${address.port}/.well-known/oauth-protected-resource/mcp`,
     );

templates/saas-product/apps/api/src/app.test.ts

@@ -4,10 +4,12 @@ import { createMcpOAuthDiscoveryRoutes } from "@codelitdev/oauth-server-kit/mcp"
 import { readOrCreateRequestId } from "@codelitdev/platform";
 import { createExpressEndpoints, initServer } from "@ts-rest/express";
 import { toNodeHandler } from "better-auth/node";
-import express, { type Express } from "express";
+import express, { type Express, type RequestHandler } from "express";
+import swaggerUi from "swagger-ui-express";
 import { AUTH_BASE_PATH, MCP_SCOPES_SUPPORTED } from "./auth/options.js";
 import type { DispatchDeps } from "./deps.js";
 import { dispatch } from "./dispatch.js";
+import { createOpenApiDocument } from "./openapi.js";
 
 export function createExpressApp(deps: DispatchDeps): Express {
   const app = express();
@@ -64,6 +66,21 @@ export function createExpressApp(deps: DispatchDeps): Express {
       loginMethods: [{ type: "email-otp" }],
     }),
   );
+  // The Swagger typings can resolve a separate Express type version in a
+  // freshly generated workspace, so normalize its handlers at this boundary.
+  app.use(
+    "/docs",
+    ...(swaggerUi.serve as unknown as RequestHandler[]),
+    swaggerUi.setup(createOpenApiDocument(deps.auth.publicApiUrl), {
+      explorer: true,
+      swaggerOptions: {
+        persistAuthorization: true,
+        displayRequestDuration: true,
+        docExpansion: "none",
+        defaultModelsExpandDepth: -1,
+      },
+    }) as unknown as RequestHandler,
+  );
   app.use(express.json({ limit: "32kb" }));
 
   const server = initServer();