rapidoc 11.0.0 → 12.0.0

package/src/utils/spec-parser.js

@@ -0,0 +1,915 @@
+import { dereference, load, upgrade } from "@scalar/openapi-parser";
+import { parse as parseYaml } from "yaml";
+import { marked } from "marked";
+import { invalidCharsRegEx, rapidocApiKey, sleep } from "./common-utils.js";
+import { OperationSlugger, toKebabCase } from "./slugger.js";
+
+function toPascalCase(str) {
+  return String(str || "")
+    .replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase())
+    .replace(/^[a-z]/, (chr) => chr.toUpperCase());
+}
+
+function isUrlLike(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const trimmed = value.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    return false;
+  }
+  if (trimmed.includes("\n")) {
+    return false;
+  }
+  return true;
+}
+
+// The page URL that relative spec URLs are resolved against; guard for non-browser environments (SSR / test runners)
+function pageUrl() {
+  return typeof window !== "undefined" && window.location?.href
+    ? window.location.href
+    : "http://localhost/";
+}
+
+/**
+ * Custom browser fetch plugin for `@scalar/openapi-parser`'s `load()` method.
+ *
+ * Provides browser-native `fetch` support for loading specifications and resolving
+ * relative and external `$ref` files across browser and SSR/Node environments.
+ *
+ * @param {string} [baseUrl] - The base URL or document path to resolve relative references against.
+ * @returns {import('@scalar/openapi-parser').LoadPlugin} A plugin object conforming to the `@scalar/openapi-parser` plugin interface:
+ *   - `check(value)`: Determines whether this plugin handles the given reference/URL.
+ *   - `resolvePath(parentPath, reference)`: Resolves relative reference paths against parent document URLs.
+ *   - `get(value)`: Fetches file content as text using browser `fetch()`.
+ */
+function createBrowserFetchPlugin(baseUrl) {
+  const base = new URL(baseUrl || pageUrl(), pageUrl());
+
+  return {
+    // Determines if the reference should be fetched by this plugin (ignores inlined JSON/YAML and '#/...' local refs)
+    check(value) {
+      if (typeof value !== "string" || value.startsWith("#")) {
+        return false;
+      }
+      return isUrlLike(value);
+    },
+    // Resolves relative $ref paths (e.g. '../common/models.yaml') against their parent document URL
+    resolvePath(parentPath, reference) {
+      if (
+        typeof reference === "string" &&
+        (reference.startsWith("http://") || reference.startsWith("https://"))
+      ) {
+        return reference;
+      }
+      const isParentString = typeof parentPath === "string";
+      const parentUrl =
+        isParentString && (parentPath.startsWith("http://") || parentPath.startsWith("https://"))
+          ? new URL(parentPath)
+          : base;
+      return new URL(reference, parentUrl).href;
+    },
+    // Fetches the target URL via native fetch and returns the parsed spec or raw text
+    async get(value) {
+      const targetUrl =
+        value.startsWith("http://") || value.startsWith("https://")
+          ? value
+          : new URL(value, base).href;
+      const resp = await fetch(targetUrl);
+      if (!resp.ok) {
+        const error = new Error(`Failed to load ${targetUrl} (${resp.status})`);
+        error.status = resp.status;
+        error.statusCode = resp.status;
+        error.response = resp;
+        error.url = targetUrl;
+        throw error;
+      }
+      const text = await resp.text();
+      try {
+        return JSON.parse(text);
+      } catch {
+        try {
+          return parseYaml(text, { maxAliasCount: -1, merge: true });
+        } catch {
+          return text;
+        }
+      }
+    },
+  };
+}
+
+function breakCircularRefs(root) {
+  const seen = new WeakMap();
+  const ancestors = new WeakSet();
+
+  function walk(node, activeRefs = new Set(), currentRef = null) {
+    if (!node || typeof node !== "object") {
+      return node;
+    }
+
+    const ref = node["x-ref"];
+    if (ref) {
+      if (activeRefs.has(ref)) {
+        return { $ref: ref };
+      }
+    }
+
+    // Cycle detection via object identity (in active ancestor chain)
+    if (ancestors.has(node)) {
+      return { $ref: ref || currentRef || "#/components/schemas/Circular" };
+    }
+
+    // Memoization for non-cycle nodes (preserves DAG sharing & linear O(V+E) time)
+    if (seen.has(node)) {
+      return seen.get(node);
+    }
+
+    ancestors.add(node);
+    let childActiveRefs = activeRefs;
+    if (ref) {
+      childActiveRefs = new Set(activeRefs);
+      childActiveRefs.add(ref);
+    }
+
+    let clone;
+    if (Array.isArray(node)) {
+      clone = [];
+      seen.set(node, clone);
+      for (let i = 0; i < node.length; i++) {
+        clone.push(walk(node[i], childActiveRefs, ref || currentRef));
+      }
+    } else {
+      clone = {};
+      seen.set(node, clone);
+      for (const key of Object.keys(node)) {
+        if (key === "x-ref") {
+          continue;
+        }
+        clone[key] = walk(node[key], childActiveRefs, ref || currentRef);
+      }
+    }
+
+    ancestors.delete(node);
+    return clone;
+  }
+
+  return walk(root);
+}
+
+export default async function ProcessSpec(
+  specUrl,
+  generateMissingTags = false,
+  sortTags = false,
+  sortSchemas = false,
+  sortEndpointsBy = "none",
+  attrApiKey = "",
+  attrApiKeyLocation = "",
+  attrApiKeyValue = "",
+  serverUrl = "",
+  matchPaths = "",
+  matchType = "",
+  removeEndpointsWithBadgeLabelAs = "",
+) {
+  let jsonParsedSpec;
+  try {
+    this?.requestUpdate?.(); // important to show the initial loader
+
+    let inputSpec = specUrl;
+    let specLocation;
+    if (typeof specUrl === "string" && isUrlLike(specUrl)) {
+      // Resolved against the page once, so the spec and its relative $refs are fetched from the same base
+      // (passing the relative path on made it relative to itself: `a/z.yaml` was fetched as `a/a/z.yaml`)
+      try {
+        specLocation = new URL(specUrl.trim(), pageUrl()).href;
+        inputSpec = specLocation;
+      } catch {
+        specLocation = specUrl;
+      }
+    } else if (typeof specUrl === "string") {
+      try {
+        inputSpec = JSON.parse(specUrl);
+      } catch {
+        try {
+          inputSpec = parseYaml(specUrl, { maxAliasCount: -1, merge: true });
+        } catch {
+          inputSpec = specUrl;
+        }
+      }
+    }
+
+    const fetchPlugin = createBrowserFetchPlugin(specLocation);
+    const loaded = await load(inputSpec, { plugins: [fetchPlugin] });
+
+    if (loaded.errors && loaded.errors.length > 0 && !loaded.specification) {
+      const firstErr = loaded.errors[0];
+      const error = new Error(firstErr.message || "Error loading specification");
+      error.status = 404;
+      throw error;
+    }
+
+    const dereferenceOptions = {
+      onDereference: ({ schema: dereferencedSchema, ref }) => {
+        dereferencedSchema["x-ref"] = ref;
+      },
+    };
+
+    let schema;
+    if (loaded.specification?.swagger && String(loaded.specification.swagger).startsWith("2")) {
+      const upgraded = upgrade(loaded.filesystem);
+      const derefResult = await dereference(upgraded.specification, dereferenceOptions);
+      schema = breakCircularRefs(derefResult.schema);
+    } else {
+      const derefResult = await dereference(loaded.filesystem, dereferenceOptions);
+      schema = breakCircularRefs(derefResult.schema);
+    }
+
+    await sleep(0); // important to show the initial loader (allows for rendering updates)
+
+    // If RapiDoc or RapiDocMini
+    if (
+      schema &&
+      (schema.components || schema.info || schema.servers || schema.tags || schema.paths)
+    ) {
+      jsonParsedSpec = filterPaths(schema, matchPaths, matchType, removeEndpointsWithBadgeLabelAs);
+      this?.dispatchEvent?.(new CustomEvent("before-render", { detail: { spec: jsonParsedSpec } }));
+    } else {
+      console.info("RapiDoc: %c Invalid Spec Definition %o ", "color:orangered", schema);
+      return {
+        specLoadError: true,
+        isSpecLoading: false,
+        info: {
+          title: "Invalid Spec Definition",
+          description: "Invalid Spec Definition",
+          version: "",
+        },
+        tags: [],
+        tagGroups: [],
+      };
+    }
+  } catch (err) {
+    let errDescr;
+    console.info(
+      "RapiDoc: %c There was an issue while loading/parsing the spec %o ",
+      "color:orangered",
+      err,
+    );
+    if (err.statusCode === 404 || err.status === 404) {
+      errDescr =
+        err.response?.url || err.url
+          ? `${err.response?.url || err.url} ┃ Not Found (${err.response?.status || err.status})`
+          : "Spec Not Found ┃ 404";
+    } else {
+      errDescr = `Unable to load ${err.response?.url || err.url || (typeof specUrl === "string" ? specUrl : "")} ┃ ${err.response?.status || err.status || err.message}`;
+    }
+    return {
+      specLoadError: true,
+      isSpecLoading: false,
+      info: {
+        title: "Error loading the spec",
+        description: errDescr,
+        version: "",
+      },
+      tags: [],
+      tagGroups: [],
+    };
+  }
+
+  const hasTagGroups = Boolean(
+    (jsonParsedSpec?.["x-tagGroups"] && jsonParsedSpec["x-tagGroups"].length > 0) ||
+    (jsonParsedSpec?.["x-tag-groups"] && jsonParsedSpec["x-tag-groups"].length > 0),
+  );
+
+  // Tags with Paths and WebHooks
+  const tags = groupByTags(
+    jsonParsedSpec,
+    sortEndpointsBy,
+    generateMissingTags,
+    sortTags,
+    hasTagGroups,
+  );
+
+  // 3-Level Tag Groups (x-tagGroups / x-tag-groups)
+  const tagGroups = groupByTagGroups(jsonParsedSpec, tags);
+
+  // Components
+  const components = getComponents(jsonParsedSpec, sortSchemas);
+
+  // Info Description Headers
+  const infoDescriptionHeaders = jsonParsedSpec.info?.description
+    ? getHeadersFromMarkdown(jsonParsedSpec.info.description)
+    : [];
+
+  // Security Scheme
+  const securitySchemes = [];
+  if (jsonParsedSpec.components?.securitySchemes) {
+    const securitySchemeSet = new Set();
+    Object.entries(jsonParsedSpec.components.securitySchemes).forEach((kv) => {
+      if (!securitySchemeSet.has(kv[0])) {
+        securitySchemeSet.add(kv[0]);
+        const securityObj = { securitySchemeId: kv[0], ...kv[1] };
+        securityObj.in = "header";
+        securityObj.name = "Authorization"; // Name of the header/cookie/api-key
+        securityObj.nameId = kv[1].name || kv[0]; // Name of the security-scheme
+        securityObj.user = "";
+        securityObj.password = "";
+        securityObj.clientId = "";
+        securityObj.clientSecret = "";
+        securityObj.value = "";
+        securityObj.finalKeyValue = "";
+        if (kv[1].type === "apiKey") {
+          securityObj.in = kv[1].in || "header";
+          securityObj.name = kv[1].name || "Authorization";
+        }
+        securitySchemes.push(securityObj);
+      }
+    });
+  }
+
+  if (attrApiKey && attrApiKeyLocation && attrApiKeyValue) {
+    securitySchemes.push({
+      securitySchemeId: rapidocApiKey,
+      description: "api-key provided in rapidoc element attributes",
+      type: "apiKey",
+      oAuthFlow: "",
+      name: attrApiKey, // Name of the header/cookie/api-key
+      nameId: attrApiKey, // Name of the security-scheme
+      in: attrApiKeyLocation,
+      value: attrApiKeyValue,
+      finalKeyValue: attrApiKeyValue,
+    });
+  }
+
+  // Updated Security Type Display Text based on Type
+  securitySchemes.forEach((v) => {
+    if (v.type === "http") {
+      v.typeDisplay = v.scheme === "basic" ? "HTTP Basic" : `HTTP Bearer ${v.nameId}`;
+    } else if (v.type === "apiKey") {
+      v.typeDisplay = `API Key (${v.name})`;
+    } else if (v.type === "oauth2") {
+      v.typeDisplay = `OAuth (${v.securitySchemeId})`;
+    } else {
+      v.typeDisplay = v.type || "None";
+    }
+  });
+
+  // Servers
+  let servers = [];
+  if (
+    jsonParsedSpec.servers &&
+    Array.isArray(jsonParsedSpec.servers) &&
+    jsonParsedSpec.servers.length > 0
+  ) {
+    jsonParsedSpec.servers.forEach((v) => {
+      let computedUrl = v.url.trim();
+      if (
+        !(
+          computedUrl.startsWith("http") ||
+          computedUrl.startsWith("//") ||
+          computedUrl.startsWith("{")
+        )
+      ) {
+        if (typeof window !== "undefined" && window.location?.origin?.startsWith("http")) {
+          v.url = window.location.origin + v.url;
+          computedUrl = v.url;
+        }
+      }
+      // Apply server-variables to generate final computed-url
+      if (v.variables) {
+        Object.entries(v.variables).forEach((kv) => {
+          const regex = new RegExp(`{${kv[0]}}`, "g");
+          computedUrl = computedUrl.replace(regex, kv[1].default || "");
+          kv[1].value = kv[1].default || "";
+        });
+      }
+      v.computedUrl = computedUrl;
+    });
+    if (serverUrl) {
+      jsonParsedSpec.servers.push({ url: serverUrl, computedUrl: serverUrl });
+    }
+  } else if (serverUrl) {
+    jsonParsedSpec.servers = [{ url: serverUrl, computedUrl: serverUrl }];
+  } else if (typeof window !== "undefined" && window.location?.origin?.startsWith("http")) {
+    jsonParsedSpec.servers = [{ url: window.location.origin, computedUrl: window.location.origin }];
+  } else {
+    jsonParsedSpec.servers = [{ url: "http://localhost", computedUrl: "http://localhost" }];
+  }
+  servers = jsonParsedSpec.servers;
+  const parsedSpec = {
+    specLoadError: false,
+    isSpecLoading: false,
+    info: jsonParsedSpec.info,
+    infoDescriptionHeaders,
+    tags,
+    tagGroups,
+    components,
+    externalDocs: jsonParsedSpec.externalDocs,
+    securitySchemes,
+    servers,
+  };
+  return parsedSpec;
+}
+
+function filterPaths(
+  openApiObject,
+  matchPaths = "",
+  matchType = "",
+  removeEndpointsWithBadgeLabelAs = "",
+) {
+  const filteredPaths = {};
+
+  // Convert the removePathsWithBadgeLabeledAs to an array if provided
+  const labelsToRemove = removeEndpointsWithBadgeLabelAs
+    .split(",")
+    .map((label) => label.trim().toLowerCase())
+    .filter(Boolean);
+
+  // Helper function to check if a path should be included based on matchPaths
+  function pathMatches(pathsKey, httpMethod) {
+    if (!matchPaths) {
+      return true; // If no matchPaths provided, include everything
+    }
+    const fullPath = `${httpMethod} ${pathsKey}`.toLowerCase(); // Construct "method path" string
+    if (matchType === "regex") {
+      const matchPathsRegex = new RegExp(matchPaths, "i");
+      return matchPathsRegex.test(fullPath);
+    }
+    return fullPath.includes(matchPaths.toLowerCase());
+  }
+
+  // Helper function to check if the badges contain any label that needs to be removed
+  function containsLabelToRemove(badges) {
+    return badges.some((badge) => labelsToRemove.includes(badge?.label.toLowerCase()));
+  }
+
+  // Loop through the paths in the openApiObject
+  Object.entries(openApiObject.paths).forEach(([pathsKey, methods]) => {
+    const filteredMethods = {};
+
+    Object.entries(methods).forEach(([httpMethod, methodDetails]) => {
+      if (
+        httpMethod === "additionalOperations" &&
+        typeof methodDetails === "object" &&
+        methodDetails !== null
+      ) {
+        const filteredAdditional = {};
+        Object.entries(methodDetails).forEach(([customMethod, customDetails]) => {
+          const badges = customDetails?.["x-badges"];
+          if (pathMatches(pathsKey, customMethod)) {
+            if (badges && Array.isArray(badges)) {
+              if (!containsLabelToRemove(badges)) {
+                filteredAdditional[customMethod] = customDetails;
+              }
+            } else {
+              filteredAdditional[customMethod] = customDetails;
+            }
+          }
+        });
+        if (Object.keys(filteredAdditional).length > 0) {
+          filteredMethods.additionalOperations = filteredAdditional;
+        }
+        return;
+      }
+
+      if (["parameters", "servers", "summary", "description"].includes(httpMethod)) {
+        filteredMethods[httpMethod] = methodDetails;
+        return;
+      }
+
+      const badges = methodDetails?.["x-badges"];
+
+      // Filter by matchPaths
+      if (pathMatches(pathsKey, httpMethod)) {
+        if (badges && Array.isArray(badges)) {
+          // Filter out based on removePathsWithBadgeLabeledAs
+          if (!containsLabelToRemove(badges)) {
+            filteredMethods[httpMethod] = methodDetails;
+          }
+        } else {
+          // No badges present, include the method
+          filteredMethods[httpMethod] = methodDetails;
+        }
+      }
+    });
+
+    if (Object.keys(filteredMethods).length > 0) {
+      filteredPaths[pathsKey] = filteredMethods;
+    }
+  });
+
+  openApiObject.paths = filteredPaths;
+  return openApiObject;
+}
+
+function getHeadersFromMarkdown(markdownContent) {
+  const tokens = marked.lexer(markdownContent);
+  const headers = tokens.filter((v) => v.type === "heading" && v.depth <= 2);
+  return headers || [];
+}
+
+function getComponents(openApiSpec, sortSchemas = false) {
+  if (!openApiSpec.components) {
+    return [];
+  }
+  const components = [];
+  for (const component in openApiSpec.components) {
+    const subComponents = [];
+    for (const sComponent in openApiSpec.components[component]) {
+      const scmp = {
+        show: true,
+        id: `${component.toLowerCase()}-${sComponent.toLowerCase()}`.replace(
+          invalidCharsRegEx,
+          "-",
+        ),
+        name: sComponent,
+        component: openApiSpec.components[component][sComponent],
+      };
+      subComponents.push(scmp);
+    }
+
+    let cmpDescription = component;
+    let cmpName = component;
+
+    switch (component) {
+      case "schemas":
+        if (sortSchemas) {
+          subComponents.sort((c1, c2) => c1.name.localeCompare(c2.name));
+        }
+
+        cmpName = "Schemas";
+        cmpDescription =
+          "Schemas allows the definition of input and output data types. These types can be objects, but also primitives and arrays.";
+        break;
+      case "responses":
+        cmpName = "Responses";
+        cmpDescription =
+          "Describes responses from an API Operation, including design-time, static links to operations based on the response.";
+        break;
+      case "parameters":
+        cmpName = "Parameters";
+        cmpDescription =
+          "Describes operation parameters. A unique parameter is defined by a combination of a name and location.";
+        break;
+      case "examples":
+        cmpName = "Examples";
+        cmpDescription =
+          "List of Examples for operations, can be requests, responses and objects examples.";
+        break;
+      case "requestBodies":
+        cmpName = "Request Bodies";
+        cmpDescription = "Describes common request bodies that are used across the API operations.";
+        break;
+      case "headers":
+        cmpName = "Headers";
+        cmpDescription =
+          'Headers follows the structure of the Parameters but they are explicitly in "header"';
+        break;
+      case "securitySchemes":
+        cmpName = "Security Schemes";
+
+        cmpDescription =
+          "Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows(implicit, password, client credentials and authorization code) as defined in RFC6749, and OpenID Connect Discovery.";
+        break;
+      case "links":
+        cmpName = "Links";
+        cmpDescription =
+          "Links represent a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.";
+        break;
+      case "callbacks":
+        cmpName = "Callbacks";
+
+        cmpDescription =
+          "A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.";
+        break;
+      default:
+        cmpName = component;
+        cmpDescription = component;
+        break;
+    }
+
+    const cmp = {
+      show: true,
+      name: cmpName,
+      description: cmpDescription,
+      subComponents,
+    };
+    components.push(cmp);
+  }
+
+  return components || [];
+}
+
+export function isTagExpanded(obj) {
+  if (!obj) {
+    return true;
+  }
+  const val = obj["x-tag-expanded"] ?? obj["x-tagExpanded"] ?? obj["x-expanded"] ?? obj.expanded;
+  if (val === false || val === "false") {
+    return false;
+  }
+  return true;
+}
+
+function groupByTags(
+  openApiSpec,
+  sortEndpointsBy = "none",
+  generateMissingTags = false,
+  sortTags = false,
+  hasTagGroups = false,
+) {
+  const supportedMethods = [
+    "get",
+    "put",
+    "post",
+    "delete",
+    "patch",
+    "head",
+    "options",
+    "trace",
+    "query",
+  ]; // this is also used for ordering endpoints by methods
+  const slugger = new OperationSlugger();
+
+  const tags =
+    openApiSpec.tags && Array.isArray(openApiSpec.tags) && openApiSpec.tags.length > 0
+      ? openApiSpec.tags.map((v) => ({
+          show: true,
+          elementId: slugger.slugTag(v.name),
+          name: v.name,
+          displayName: v["x-displayName"] || v.name,
+          description: v.description || "",
+          headers: v.description ? getHeadersFromMarkdown(v.description) : [],
+          paths: [],
+          expanded: isTagExpanded(v),
+          xInternal: v["x-internal"] ?? undefined,
+          xHidden: v["x-hidden"] ?? undefined,
+        }))
+      : [];
+
+  const pathsAndWebhooks = openApiSpec.paths || {};
+  if (openApiSpec.webhooks) {
+    for (const [key, value] of Object.entries(openApiSpec.webhooks)) {
+      value._type = "webhook";
+      pathsAndWebhooks[key] = value;
+    }
+  }
+  // For each path find the tag and push it into the corresponding tag
+  for (const pathOrHookName in pathsAndWebhooks) {
+    const commonParams = pathsAndWebhooks[pathOrHookName].parameters;
+    const commonPathProp = {
+      servers: pathsAndWebhooks[pathOrHookName].servers || [],
+      parameters: pathsAndWebhooks[pathOrHookName].parameters || [],
+    };
+    const isWebhook = pathsAndWebhooks[pathOrHookName]._type === "webhook";
+    const operationsToProcess = [];
+    supportedMethods.forEach((methodName) => {
+      if (pathsAndWebhooks[pathOrHookName][methodName]) {
+        operationsToProcess.push({
+          methodName,
+          pathOrHookObj: pathsAndWebhooks[pathOrHookName][methodName],
+        });
+      }
+    });
+
+    if (
+      pathsAndWebhooks[pathOrHookName].additionalOperations &&
+      typeof pathsAndWebhooks[pathOrHookName].additionalOperations === "object"
+    ) {
+      Object.entries(pathsAndWebhooks[pathOrHookName].additionalOperations).forEach(
+        ([customMethod, customObj]) => {
+          if (customObj && typeof customObj === "object") {
+            operationsToProcess.push({
+              methodName: customMethod.toLowerCase(),
+              pathOrHookObj: customObj,
+            });
+          }
+        },
+      );
+    }
+
+    operationsToProcess.forEach(({ methodName, pathOrHookObj }) => {
+      // If path.methods are tagged, else generate it from path
+      const pathTags = pathOrHookObj.tags || [];
+      if (pathTags.length === 0) {
+        if (generateMissingTags) {
+          const pathOrHookNameKey = pathOrHookName.replace(/^\/+|\/+$/g, "");
+          const firstWordEndIndex = pathOrHookNameKey.indexOf("/");
+          if (firstWordEndIndex === -1) {
+            pathTags.push(pathOrHookNameKey);
+          } else {
+            // firstWordEndIndex -= 1;
+            pathTags.push(pathOrHookNameKey.substring(0, firstWordEndIndex));
+          }
+        } else {
+          pathTags.push("General");
+        }
+      }
+
+      pathTags.forEach((tag) => {
+        let tagObj;
+        let specTagsItem;
+
+        if (openApiSpec.tags) {
+          specTagsItem = openApiSpec.tags.find((v) => v.name.toLowerCase() === tag.toLowerCase());
+        }
+
+        tagObj = tags.find((v) => v.name === tag);
+        if (!tagObj) {
+          tagObj = {
+            show: true,
+            elementId: slugger.slugTag(tag),
+            name: tag,
+            displayName: specTagsItem?.["x-displayName"] || specTagsItem?.name || tag,
+            description: specTagsItem?.description || "",
+            headers: specTagsItem?.description
+              ? getHeadersFromMarkdown(specTagsItem.description)
+              : [],
+            paths: [],
+            expanded: isTagExpanded(specTagsItem),
+            xInternal: specTagsItem?.["x-internal"] ?? undefined,
+            xHidden: specTagsItem?.["x-hidden"] ?? undefined,
+          };
+          tags.push(tagObj);
+        }
+
+        // Generate a short summary which is broken
+        let shortSummary = (
+          pathOrHookObj.summary ||
+          pathOrHookObj.description ||
+          `${methodName.toUpperCase()} ${pathOrHookName}`
+        ).trim();
+        if (shortSummary.length > 100) {
+          [shortSummary] = shortSummary.split(/[.|!|?]\s|[\r?\n]/); // take the first line (period or carriage return)
+        }
+        // Merge Common Parameters with This methods parameters
+        let finalParameters = [];
+        if (commonParams) {
+          if (pathOrHookObj.parameters) {
+            finalParameters = commonParams
+              .filter((commonParam) => {
+                if (
+                  !pathOrHookObj.parameters.some(
+                    (param) => commonParam.name === param.name && commonParam.in === param.in,
+                  )
+                ) {
+                  return commonParam;
+                }
+              })
+              .concat(pathOrHookObj.parameters);
+          } else {
+            finalParameters = commonParams.slice(0);
+          }
+        } else {
+          finalParameters = pathOrHookObj.parameters ? pathOrHookObj.parameters.slice(0) : [];
+        }
+
+        // Filter callbacks to contain only objects.
+        if (pathOrHookObj.callbacks) {
+          for (const [callbackName, callbackConfig] of Object.entries(pathOrHookObj.callbacks)) {
+            const filteredCallbacks =
+              Object.entries(callbackConfig).filter((entry) => typeof entry[1] === "object") || [];
+            pathOrHookObj.callbacks[callbackName] = Object.fromEntries(filteredCallbacks);
+          }
+        }
+
+        const cleanPath = (pathOrHookName || "")
+          .replace(/[{}]/g, "")
+          .replace(/[^a-zA-Z0-9]+/g, "-")
+          .replace(/^-+|-+$/g, "");
+        const fallbackOpId = `${methodName}${toPascalCase(cleanPath)}`;
+        const operationId = pathOrHookObj.operationId || fallbackOpId;
+        const tagSlug = hasTagGroups ? toKebabCase(tag) : "";
+        const elementId = slugger.slug(
+          {
+            method: methodName,
+            path: pathOrHookName,
+            operationId: pathOrHookObj.operationId,
+            summary: pathOrHookObj.summary || pathOrHookObj.description,
+          },
+          tagSlug,
+        );
+
+        // Update Responses
+        tagObj.paths.push({
+          show: true,
+          expanded: false,
+          isWebhook,
+          expandedAtLeastOnce: false,
+          summary: pathOrHookObj.summary || "",
+          description: pathOrHookObj.description || "",
+          externalDocs: pathOrHookObj.externalDocs,
+          shortSummary,
+          method: methodName,
+          path: pathOrHookName,
+          operationId,
+          elementId,
+          servers: pathOrHookObj.servers
+            ? commonPathProp.servers.concat(pathOrHookObj.servers)
+            : commonPathProp.servers,
+          parameters: finalParameters,
+          requestBody: pathOrHookObj.requestBody,
+          responses: pathOrHookObj.responses,
+          callbacks: pathOrHookObj.callbacks,
+          deprecated: pathOrHookObj.deprecated,
+          security: pathOrHookObj.security ?? openApiSpec.security,
+          // commonSummary: commonPathProp.summary,
+          // commonDescription: commonPathProp.description,
+          xBadges: pathOrHookObj["x-badges"] || undefined,
+          xCodeSamples: pathOrHookObj["x-codeSamples"] || pathOrHookObj["x-code-samples"] || "",
+          rawOperation: pathOrHookObj,
+          xMcp: pathOrHookObj["x-mcp"] || pathOrHookObj["x-mcp-tool"] || undefined,
+          xInternal:
+            pathOrHookObj["x-internal"] ??
+            pathsAndWebhooks[pathOrHookName]?.["x-internal"] ??
+            undefined,
+          xHidden:
+            pathOrHookObj["x-hidden"] ??
+            pathsAndWebhooks[pathOrHookName]?.["x-hidden"] ??
+            undefined,
+          xOpenAiIsConsequential: pathOrHookObj["x-openai-isConsequential"],
+          xSpeakeasyNameOverride: pathOrHookObj["x-speakeasy-name-override"] || undefined,
+        });
+      }); // End of tag path create
+    }); // End of operationsToProcess
+  }
+
+  const tagsWithSortedPaths = tags.filter((tag) => tag.paths && tag.paths.length > 0);
+  tagsWithSortedPaths.forEach((tag) => {
+    if (sortEndpointsBy !== "none") {
+      if (sortEndpointsBy === "method") {
+        tag.paths.sort((a, b) => {
+          const idxA = supportedMethods.indexOf(a.method);
+          const idxB = supportedMethods.indexOf(b.method);
+          if (idxA !== -1 && idxB !== -1) {
+            return idxA - idxB;
+          }
+          if (idxA !== -1) {
+            return -1;
+          }
+          if (idxB !== -1) {
+            return 1;
+          }
+          return a.method.localeCompare(b.method);
+        });
+      } else if (sortEndpointsBy === "summary") {
+        tag.paths.sort((a, b) => a.shortSummary.localeCompare(b.shortSummary));
+      } else if (sortEndpointsBy === "path") {
+        tag.paths.sort((a, b) => a.path.localeCompare(b.path));
+      }
+    }
+    tag.firstPathId = tag.paths[0]?.elementId || "";
+  });
+  return sortTags
+    ? tagsWithSortedPaths.sort((a, b) => a.name.localeCompare(b.name))
+    : tagsWithSortedPaths;
+}
+
+/**
+ * Organizes parsed tags into 3-tier tag groups based on the `x-tagGroups` or `x-tag-groups` vendor extension.
+ * If the extension is absent, returns an empty array to maintain backward-compatible 2-tier navigation.
+ *
+ * @param {object} openApiSpec - The root OpenAPI specification object.
+ * @param {Array<object>} tags - The processed tags array returned by groupByTags.
+ * @returns {Array<object>} Array of tag group objects, or empty array if no tag groups are defined.
+ */
+export function groupByTagGroups(openApiSpec, tags = []) {
+  const rawGroups =
+    openApiSpec?.["x-tagGroups"] || openApiSpec?.["x-tag-groups"] || openApiSpec?.["x-taggroups"];
+  if (!rawGroups || !Array.isArray(rawGroups) || rawGroups.length === 0) {
+    return [];
+  }
+
+  const slugger = new OperationSlugger();
+  const assignedTagNames = new Set();
+  const groups = [];
+
+  rawGroups.forEach((g) => {
+    if (!g || !g.name) return;
+    const targetTagNames = Array.isArray(g.tags) ? g.tags : [];
+    const groupTags = [];
+    targetTagNames.forEach((tName) => {
+      if (typeof tName !== "string") return;
+      const foundTag = tags.find(
+        (t) => t.name === tName || t.name.toLowerCase() === tName.toLowerCase(),
+      );
+      if (foundTag && !groupTags.includes(foundTag)) {
+        groupTags.push(foundTag);
+        assignedTagNames.add(foundTag.name);
+      }
+    });
+
+    if (groupTags.length > 0) {
+      groups.push({
+        name: g.name,
+        displayName: g["x-displayName"] || g.displayName || g.name,
+        description: g.description || "",
+        elementId: slugger.slugTagGroup(g.name),
+        tags: groupTags,
+        expanded: isTagExpanded(g),
+        xInternal: g["x-internal"] ?? undefined,
+        xHidden: g["x-hidden"] ?? undefined,
+      });
+    }
+  });
+
+  return groups;
+}