feat: CI job to detect breaking api v2 changes (#24028)

* refactor: move swagger to src/swagger

* refactor: standalone swagger generation script

* refactor: generate only 1 swagger file

* feat: github action checking breaking changes

* chore: ensure openapi file is formatted

* chore: run breaking change check on label

* chore: have only 1 swagger file

* fix: run breaking changes check on workflow call

* refactor: pr breaking jobs dependency

* fix: copy swagger module

* refactor: add check-label as dep

* refactor: breaking changes check part of v2 e2e workflow

* refactor: run breaking changes before e2e

* chore: add vapid env keys to workflow

* chore: add CI_JWT_SECRET to e2e api v2

* chore: add NODE_ENV

---------

Co-authored-by: cal.com <morgan@cal.com>

.github/workflows/e2e-api-v2.yml

@@ -1,4 +1,4 @@
-name: E2E
+name: Check breaking changes and run E2E
 on:
   workflow_call:
 env:
@@ -23,6 +23,10 @@ env:
   STRIPE_CLIENT_ID: ${{ secrets.CI_STRIPE_CLIENT_ID }}
   STRIPE_WEBHOOK_SECRET: ${{ secrets.CI_STRIPE_WEBHOOK_SECRET }}
   SLOTS_CACHE_TTL: ${{ secrets.CI_SLOTS_CACHE_TTL }}
+  NEXT_PUBLIC_VAPID_PUBLIC_KEY: ${{ secrets.NEXT_PUBLIC_VAPID_PUBLIC_KEY }}
+  VAPID_PRIVATE_KEY: ${{ secrets.VAPID_PRIVATE_KEY }}
+  JWT_SECRET: ${{ secrets.CI_JWT_SECRET }}
+  NODE_ENV: ${{ vars.CI_NODE_ENV }}
 jobs:
   e2e:
     timeout-minutes: 20
@@ -68,6 +72,18 @@ jobs:
       - uses: ./.github/actions/dangerous-git-checkout
       - uses: ./.github/actions/yarn-install
       - uses: ./.github/actions/cache-db
+      
+      - name: Generate Swagger
+        working-directory: apps/api/v2
+        run: yarn generate-swagger
+
+      - name: Check breaking changes
+        uses: oasdiff/oasdiff-action/breaking@main
+        with:
+          base: https://raw.githubusercontent.com/calcom/cal.com/refs/heads/main/docs/api-reference/v2/openapi.json
+          revision: docs/api-reference/v2/openapi.json
+          fail-on: WARN
+          
       - name: Run Tests
         working-directory: apps/api/v2
         run: |
@@ -75,6 +91,7 @@ jobs:
           EXIT_CODE=$?
           echo "yarn workspace @calcom/platform-libraries build && yarn test:e2e command exit code: $EXIT_CODE"
           exit $EXIT_CODE
+          
       - name: Upload Test Results
         if: ${{ always() }}
         uses: actions/upload-artifact@v4

.prettierignore

@@ -16,5 +16,4 @@ public
 packages/prisma/zod
 packages/prisma/enums
 apps/web/public/embed
-apps/api/v2/swagger/documentation.json
 packages/ui/components/icon/dynamicIconImports.tsx

apps/api/v2/package.json

@@ -16,7 +16,7 @@
     "_dev:build:watch:enums": "yarn workspace @calcom/platform-enums build:watch",
     "_dev:build:watch:utils": "yarn workspace @calcom/platform-utils build:watch",
     "_dev:build:watch:types": "yarn workspace @calcom/platform-types build:watch",
-    "dev:build": "yarn workspace @calcom/platform-constants build && yarn workspace @calcom/platform-enums build && yarn workspace @calcom/platform-utils build && yarn workspace @calcom/platform-types build",
+    "dev:build": "yarn workspace @calcom/platform-constants build && yarn workspace @calcom/platform-enums build && yarn workspace @calcom/platform-utils build && yarn workspace @calcom/platform-types build && yarn workspace @calcom/platform-libraries build",
     "dev": "yarn dev:build && ts-node scripts/docker-start.ts && yarn copy-swagger-module && yarn start --watch",
     "dev:no-docker": "yarn dev:build && yarn copy-swagger-module && yarn start --watch",
     "start:debug": "nest start --debug --watch",
@@ -30,7 +30,8 @@
     "test:e2e:watch": "yarn dev:build && jest --runInBand --detectOpenHandles --forceExit --config ./jest-e2e.ts --watch",
     "prisma": "yarn workspace @calcom/prisma prisma",
     "generate-schemas": "yarn prisma generate && yarn prisma format",
-    "copy-swagger-module": "ts-node -r tsconfig-paths/register swagger/copy-swagger-module.ts",
+    "copy-swagger-module": "ts-node -r tsconfig-paths/register src/swagger/copy-swagger-module.ts",
+    "generate-swagger": "yarn copy-swagger-module && yarn build && node ./dist/apps/api/v2/src/swagger/generate-swagger-script.js",
     "prepare": "yarn run snyk-protect",
     "snyk-protect": "snyk-protect"
   },

apps/api/v2/src/main.ts

@@ -1,39 +1,29 @@
 import type { AppConfig } from "@/config/type";
-import { getEnv } from "@/env";
 import { Logger } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { NestFactory } from "@nestjs/core";
 import type { NestExpressApplication } from "@nestjs/platform-express";
-import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";
-import {
-  PathItemObject,
-  PathsObject,
-  OperationObject,
-  TagObject,
-} from "@nestjs/swagger/dist/interfaces/open-api-spec.interface";
 import "dotenv/config";
-import * as fs from "fs";
-import { Server } from "http";
 import { WinstonModule } from "nest-winston";
 
 import { bootstrap } from "./app";
 import { AppModule } from "./app.module";
 import { loggerConfig } from "./lib/logger";
+import { generateSwaggerForApp } from "./swagger/generate-swagger";
 
-const HttpMethods: (keyof PathItemObject)[] = ["get", "post", "put", "delete", "patch", "options", "head"];
-
-const run = async () => {
-  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
-    logger: WinstonModule.createLogger(loggerConfig()),
-    bodyParser: false,
-  });
+run().catch((error: Error) => {
+  console.error("Failed to start Cal Platform API", { error: error.stack });
+  process.exit(1);
+});
 
+async function run() {
+  const app = await createNestApp();
   const logger = new Logger("App");
 
   try {
     bootstrap(app);
     const port = app.get(ConfigService<AppConfig, true>).get("api.port", { infer: true });
-    void generateSwagger(app);
+    generateSwaggerForApp(app);
     await app.listen(port);
     logger.log(`Application started on port: ${port}`);
   } catch (error) {
@@ -42,97 +32,11 @@ const run = async () => {
       error,
     });
   }
-};
-
-function customTagSort(a: string, b: string): number {
-  const platformPrefix = "Platform";
-  const orgsPrefix = "Orgs";
-
-  if (a.startsWith(platformPrefix) && !b.startsWith(platformPrefix)) {
-    return -1;
-  }
-  if (!a.startsWith(platformPrefix) && b.startsWith(platformPrefix)) {
-    return 1;
-  }
-
-  if (a.startsWith(orgsPrefix) && !b.startsWith(orgsPrefix)) {
-    return -1;
-  }
-  if (!a.startsWith(orgsPrefix) && b.startsWith(orgsPrefix)) {
-    return 1;
-  }
-
-  return a.localeCompare(b);
 }
 
-function isOperationObject(obj: any): obj is OperationObject {
-  return obj && typeof obj === "object" && "tags" in obj;
-}
-
-function groupAndSortPathsByFirstTag(paths: PathsObject): PathsObject {
-  const groupedPaths: { [key: string]: PathsObject } = {};
-
-  Object.keys(paths).forEach((pathKey) => {
-    const pathItem = paths[pathKey];
-
-    HttpMethods.forEach((method) => {
-      const operation = pathItem[method];
-
-      if (isOperationObject(operation) && operation.tags && operation.tags.length > 0) {
-        const firstTag = operation.tags[0];
-
-        if (!groupedPaths[firstTag]) {
-          groupedPaths[firstTag] = {};
-        }
-
-        groupedPaths[firstTag][pathKey] = pathItem;
-      }
-    });
+export async function createNestApp() {
+  return NestFactory.create<NestExpressApplication>(AppModule, {
+    logger: WinstonModule.createLogger(loggerConfig()),
+    bodyParser: false,
   });
-
-  const sortedTags = Object.keys(groupedPaths).sort(customTagSort);
-  const sortedPaths: PathsObject = {};
-
-  sortedTags.forEach((tag) => {
-    Object.assign(sortedPaths, groupedPaths[tag]);
-  });
-
-  return sortedPaths;
 }
-
-async function generateSwagger(app: NestExpressApplication<Server>) {
-  const logger = new Logger("App");
-  logger.log(`Generating Swagger documentation...\n`);
-
-  const config = new DocumentBuilder().setTitle("Cal.com API v2").build();
-  const document = SwaggerModule.createDocument(app, config);
-  document.paths = groupAndSortPathsByFirstTag(document.paths);
-
-  const swaggerOutputFile = "./swagger/documentation.json";
-  const docsOutputFile = "../../../docs/api-reference/v2/openapi.json";
-  const stringifiedContents = JSON.stringify(document, null, 2);
-
-  if (fs.existsSync(swaggerOutputFile)) {
-    fs.unlinkSync(swaggerOutputFile);
-  }
-
-  fs.writeFileSync(swaggerOutputFile, stringifiedContents, { encoding: "utf8" });
-
-  if (fs.existsSync(docsOutputFile) && getEnv("NODE_ENV") === "development") {
-    fs.unlinkSync(docsOutputFile);
-    fs.writeFileSync(docsOutputFile, stringifiedContents, { encoding: "utf8" });
-  }
-
-  if (!process.env.DOCS_URL) {
-    SwaggerModule.setup("docs", app, document, {
-      customCss: ".swagger-ui .topbar { display: none }",
-    });
-
-    logger.log(`Swagger documentation available in the "/docs" endpoint\n`);
-  }
-}
-
-run().catch((error: Error) => {
-  console.error("Failed to start Cal Platform API", { error: error.stack });
-  process.exit(1);
-});

apps/api/v2/src/swagger/copy-swagger-module.ts

@@ -8,8 +8,8 @@ import * as path from "path";
 // "nest-cli" with the "nest-cli.json" file, and for nest cli to be loaded with plugins correctly the "@nestjs/swagger"
 // should reside in the project's node_modules already before the "nest start" command is executed.
 async function copyNestSwagger() {
-  const monorepoRoot = path.resolve(__dirname, "../../../../");
-  const nodeModulesNestjs = path.resolve(__dirname, "../node_modules/@nestjs");
+  const monorepoRoot = path.resolve(__dirname, "../../../../../");
+  const nodeModulesNestjs = path.resolve(__dirname, "../../node_modules/@nestjs");
   const swaggerModulePath = "@nestjs/swagger";
 
   const sourceDir = path.join(monorepoRoot, "node_modules", swaggerModulePath);

apps/api/v2/src/swagger/generate-swagger-script.ts

@@ -0,0 +1,29 @@
+import "dotenv/config";
+
+import { bootstrap } from "../app";
+import { createNestApp } from "../main";
+import { generateSwaggerForApp } from "../swagger/generate-swagger";
+
+generateSwagger()
+  .then(() => {
+    console.log("✅ Swagger generation completed successfully");
+    process.exit(0);
+  })
+  .catch((error: Error) => {
+    console.error("❌ Failed to generate swagger", { error: error.stack });
+    process.exit(1);
+  });
+
+async function generateSwagger() {
+  const app = await createNestApp();
+
+  try {
+    bootstrap(app);
+    await generateSwaggerForApp(app);
+  } catch (error) {
+    console.error(error);
+    throw error;
+  } finally {
+    await app.close();
+  }
+}

apps/api/v2/src/swagger/generate-swagger.ts

@@ -0,0 +1,97 @@
+import { getEnv } from "@/env";
+import { Logger } from "@nestjs/common";
+import type { NestExpressApplication } from "@nestjs/platform-express";
+import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";
+import {
+  PathItemObject,
+  PathsObject,
+  OperationObject,
+} from "@nestjs/swagger/dist/interfaces/open-api-spec.interface";
+import "dotenv/config";
+import * as fs from "fs";
+import { Server } from "http";
+import { spawnSync } from "node:child_process";
+
+const HttpMethods: (keyof PathItemObject)[] = ["get", "post", "put", "delete", "patch", "options", "head"];
+
+export async function generateSwaggerForApp(app: NestExpressApplication<Server>) {
+  const logger = new Logger("App");
+  logger.log(`Generating Swagger documentation...\n`);
+
+  const config = new DocumentBuilder().setTitle("Cal.com API v2").build();
+  const document = SwaggerModule.createDocument(app, config);
+  document.paths = groupAndSortPathsByFirstTag(document.paths);
+
+  const docsOutputFile = "../../../docs/api-reference/v2/openapi.json";
+  const stringifiedContents = JSON.stringify(document, null, 2);
+
+  if (fs.existsSync(docsOutputFile) && getEnv("NODE_ENV") === "development") {
+    fs.unlinkSync(docsOutputFile);
+    fs.writeFileSync(docsOutputFile, stringifiedContents, { encoding: "utf8" });
+    spawnSync("npx", ["prettier", docsOutputFile, "--write"], { stdio: "inherit" });
+  }
+
+  if (!process.env.DOCS_URL) {
+    SwaggerModule.setup("docs", app, document, {
+      customCss: ".swagger-ui .topbar { display: none }",
+    });
+
+    logger.log(`Swagger documentation available in the "/docs" endpoint\n`);
+  }
+}
+
+function groupAndSortPathsByFirstTag(paths: PathsObject): PathsObject {
+  const groupedPaths: { [key: string]: PathsObject } = {};
+
+  Object.keys(paths).forEach((pathKey) => {
+    const pathItem = paths[pathKey];
+
+    HttpMethods.forEach((method) => {
+      const operation = pathItem[method];
+
+      if (isOperationObject(operation) && operation.tags && operation.tags.length > 0) {
+        const firstTag = operation.tags[0];
+
+        if (!groupedPaths[firstTag]) {
+          groupedPaths[firstTag] = {};
+        }
+
+        groupedPaths[firstTag][pathKey] = pathItem;
+      }
+    });
+  });
+
+  const sortedTags = Object.keys(groupedPaths).sort(customTagSort);
+  const sortedPaths: PathsObject = {};
+
+  sortedTags.forEach((tag) => {
+    Object.assign(sortedPaths, groupedPaths[tag]);
+  });
+
+  return sortedPaths;
+}
+
+function customTagSort(a: string, b: string): number {
+  const platformPrefix = "Platform";
+  const orgsPrefix = "Orgs";
+
+  if (a.startsWith(platformPrefix) && !b.startsWith(platformPrefix)) {
+    return -1;
+  }
+  if (!a.startsWith(platformPrefix) && b.startsWith(platformPrefix)) {
+    return 1;
+  }
+
+  if (a.startsWith(orgsPrefix) && !b.startsWith(orgsPrefix)) {
+    return -1;
+  }
+  if (!a.startsWith(orgsPrefix) && b.startsWith(orgsPrefix)) {
+    return 1;
+  }
+
+  return a.localeCompare(b);
+}
+
+function isOperationObject(obj: any): obj is OperationObject {
+  return obj && typeof obj === "object" && "tags" in obj;
+}