chore: Add sorting to API v2 OpenAPI doc (#16786)

apps/api/v2/src/main.ts

@@ -4,6 +4,12 @@ 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";
@@ -13,6 +19,8 @@ import { bootstrap } from "./app";
 import { AppModule } from "./app.module";
 import { loggerConfig } from "./lib/logger";
 
+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()),
@@ -35,12 +43,70 @@ const run = async () => {
   }
 };
 
+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;
+      }
+    });
+  });
+
+  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 outputFile = "./swagger/documentation.json";
 
   if (fs.existsSync(outputFile)) {