@camunda8/docusaurus-plugin-openapi-docs 4.5.2 → 4.5.3

package/lib/openapi/sdkExamples.js

@@ -49,13 +49,24 @@ function extractRegion(content, regionName) {
             // Check if this line is an end marker for our region
             for (const pattern of REGION_PATTERNS) {
                 const endMatch = line.match(pattern.end);
-                if (endMatch &&
-                    (!endMatch[1] || endMatch[1].trim() === regionName)) {
+                if (endMatch && (!endMatch[1] || endMatch[1].trim() === regionName)) {
                     // Found end marker — return captured content
                     return trimIndentation(capturedLines);
                 }
             }
-            capturedLines.push(line);
+            // Skip nested region markers for the same region name
+            // (e.g. C# files may have both #region and // <Name> markers)
+            let isNestedMarker = false;
+            for (const pattern of REGION_PATTERNS) {
+                const startMatch = line.match(pattern.start);
+                if (startMatch && startMatch[1].trim() === regionName) {
+                    isNestedMarker = true;
+                    break;
+                }
+            }
+            if (!isNestedMarker) {
+                capturedLines.push(line);
+            }
         }
         else {
             // Check if this line is a start marker for our region
@@ -87,6 +98,13 @@ function trimIndentation(lines) {
         .join("\n")
         .trim();
 }
+/**
+ * Convert a camelCase string to snake_case.
+ * e.g. "activateJobs" -> "activate_jobs"
+ */
+function camelToSnake(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
 /**
  * Build x-codeSamples entries for a given operationId from all configured SDK sources.
  *
@@ -110,7 +128,9 @@ function buildCodeSamples(operationId, sdkExamples, siteDir, fileCache, mapCache
             operationMap = fs_extra_1.default.readJSONSync(mapPath);
             mapCache.set(mapPath, operationMap);
         }
-        const entries = operationMap[operationId];
+        // Try exact match first, then fall back to snake_case conversion
+        // (Python SDKs conventionally use snake_case operationIds)
+        const entries = operationMap[operationId] || operationMap[camelToSnake(operationId)];
         if (!entries || entries.length === 0)
             continue;
         const mapDir = path_1.default.dirname(mapPath);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@camunda8/docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "4.5.2",
+  "version": "4.5.3",
   "license": "MIT",
   "keywords": [
     "openapi",

package/src/openapi/sdkExamples.ts

@@ -1,195 +1,215 @@
-/* ============================================================================
- * Copyright (c) Palo Alto Networks
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- * ========================================================================== */
-
-import path from "path";
-
-import fs from "fs-extra";
-
-/**
- * Configuration for a single SDK example source.
- */
-export interface SdkExampleSource {
-  /** Language label shown in the code sample tab (e.g. "TypeScript", "Python", "C#"). */
-  lang: string;
-  /** Syntax highlight mode (e.g. "typescript", "python", "csharp"). */
-  highlight?: string;
-  /** Path to the operation-map.json file (relative to site root or absolute). */
-  operationMapPath: string;
-}
-
-/**
- * A single entry in operation-map.json for one operationId.
- */
-interface OperationMapEntry {
-  file: string;
-  region: string;
-  label?: string;
-}
-
-/**
- * Shape of operation-map.json: operationId -> entries[].
- */
-type OperationMap = Record<string, OperationMapEntry[]>;
-
-// Region marker patterns for supported languages.
-// Each pattern matches the start/end of a named region.
-const REGION_PATTERNS: {
-  start: RegExp;
-  end: RegExp;
-}[] = [
-  // TypeScript/JavaScript: //#region Name  ...  //#endregion [Name]
-  {
-    start: /^\s*\/\/#region\s+(.+?)\s*$/,
-    end: /^\s*\/\/#endregion(?:\s+(.+?))?\s*$/,
-  },
-  // C#: #region Name  ...  #endregion [Name]
-  {
-    start: /^\s*#region\s+(.+?)\s*$/,
-    end: /^\s*#endregion(?:\s+(.+?))?\s*$/,
-  },
-  // XML-style: // <RegionName>  ...  // </RegionName>
-  {
-    start: /^\s*\/\/\s*<([A-Za-z]\w*)>\s*$/,
-    end: /^\s*\/\/\s*<\/([A-Za-z]\w*)>\s*$/,
-  },
-  // Python: # region Name  ...  # endregion [Name]
-  {
-    start: /^\s*#\s*region\s+(.+?)\s*$/,
-    end: /^\s*#\s*endregion(?:\s+(.+?))?\s*$/,
-  },
-];
-
-/**
- * Extract the code between region markers from a source file's content.
- * Returns the trimmed code block or undefined if the region is not found.
- */
-function extractRegion(
-  content: string,
-  regionName: string
-): string | undefined {
-  const lines = content.split(/\r?\n/);
-  let capturing = false;
-  let capturedLines: string[] = [];
-
-  for (const line of lines) {
-    if (capturing) {
-      // Check if this line is an end marker for our region
-      for (const pattern of REGION_PATTERNS) {
-        const endMatch = line.match(pattern.end);
-        if (
-          endMatch &&
-          (!endMatch[1] || endMatch[1].trim() === regionName)
-        ) {
-          // Found end marker — return captured content
-          return trimIndentation(capturedLines);
-        }
-      }
-      capturedLines.push(line);
-    } else {
-      // Check if this line is a start marker for our region
-      for (const pattern of REGION_PATTERNS) {
-        const startMatch = line.match(pattern.start);
-        if (startMatch && startMatch[1].trim() === regionName) {
-          capturing = true;
-          capturedLines = [];
-          break;
-        }
-      }
-    }
-  }
-
-  return undefined;
-}
-
-/**
- * Remove the common leading whitespace from all non-empty lines.
- */
-function trimIndentation(lines: string[]): string {
-  const nonEmptyLines = lines.filter((l) => l.trim().length > 0);
-  if (nonEmptyLines.length === 0) return "";
-
-  const minIndent = Math.min(
-    ...nonEmptyLines.map((l) => {
-      const match = l.match(/^(\s*)/);
-      return match ? match[1].length : 0;
-    })
-  );
-
-  return lines
-    .map((l) => (l.trim().length === 0 ? "" : l.slice(minIndent)))
-    .join("\n")
-    .trim();
-}
-
-/**
- * Build x-codeSamples entries for a given operationId from all configured SDK sources.
- *
- * @param operationId - The OpenAPI operationId to look up.
- * @param sdkExamples - Array of SDK example source configurations.
- * @param siteDir - The Docusaurus site root directory (for resolving relative paths).
- * @param fileCache - Shared cache to avoid re-reading the same source files.
- * @param mapCache - Shared cache for parsed operation-map.json files.
- * @returns Array of x-codeSamples entries, or empty array if none found.
- */
-export function buildCodeSamples(
-  operationId: string,
-  sdkExamples: SdkExampleSource[],
-  siteDir: string,
-  fileCache: Map<string, string>,
-  mapCache: Map<string, OperationMap>
-): { lang: string; label: string; source: string }[] {
-  const samples: { lang: string; label: string; source: string }[] = [];
-
-  for (const sdk of sdkExamples) {
-    const mapPath = path.resolve(siteDir, sdk.operationMapPath);
-    let operationMap = mapCache.get(mapPath);
-    if (!operationMap) {
-      if (!fs.existsSync(mapPath)) {
-        console.warn(`SDK examples: operation-map not found at ${mapPath}`);
-        continue;
-      }
-      operationMap = fs.readJSONSync(mapPath) as OperationMap;
-      mapCache.set(mapPath, operationMap);
-    }
-
-    const entries = operationMap[operationId];
-    if (!entries || entries.length === 0) continue;
-
-    const mapDir = path.dirname(mapPath);
-
-    for (const entry of entries) {
-      const filePath = path.resolve(mapDir, entry.file);
-      let fileContent = fileCache.get(filePath);
-      if (fileContent === undefined) {
-        if (!fs.existsSync(filePath)) {
-          console.warn(
-            `SDK examples: source file not found at ${filePath} (referenced by ${sdk.lang} operation-map for ${operationId})`
-          );
-          continue;
-        }
-        fileContent = fs.readFileSync(filePath, "utf-8");
-        fileCache.set(filePath, fileContent);
-      }
-
-      const code = extractRegion(fileContent, entry.region);
-      if (!code) {
-        console.warn(
-          `SDK examples: region "${entry.region}" not found in ${filePath} (${sdk.lang}, ${operationId})`
-        );
-        continue;
-      }
-
-      samples.push({
-        lang: sdk.lang,
-        label: "SDK",
-        source: code,
-      });
-    }
-  }
-
-  return samples;
-}
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import path from "path";
+
+import fs from "fs-extra";
+
+/**
+ * Configuration for a single SDK example source.
+ */
+export interface SdkExampleSource {
+  /** Language label shown in the code sample tab (e.g. "TypeScript", "Python", "C#"). */
+  lang: string;
+  /** Syntax highlight mode (e.g. "typescript", "python", "csharp"). */
+  highlight?: string;
+  /** Path to the operation-map.json file (relative to site root or absolute). */
+  operationMapPath: string;
+}
+
+/**
+ * A single entry in operation-map.json for one operationId.
+ */
+interface OperationMapEntry {
+  file: string;
+  region: string;
+  label?: string;
+}
+
+/**
+ * Shape of operation-map.json: operationId -> entries[].
+ */
+type OperationMap = Record<string, OperationMapEntry[]>;
+
+// Region marker patterns for supported languages.
+// Each pattern matches the start/end of a named region.
+const REGION_PATTERNS: {
+  start: RegExp;
+  end: RegExp;
+}[] = [
+  // TypeScript/JavaScript: //#region Name  ...  //#endregion [Name]
+  {
+    start: /^\s*\/\/#region\s+(.+?)\s*$/,
+    end: /^\s*\/\/#endregion(?:\s+(.+?))?\s*$/,
+  },
+  // C#: #region Name  ...  #endregion [Name]
+  {
+    start: /^\s*#region\s+(.+?)\s*$/,
+    end: /^\s*#endregion(?:\s+(.+?))?\s*$/,
+  },
+  // XML-style: // <RegionName>  ...  // </RegionName>
+  {
+    start: /^\s*\/\/\s*<([A-Za-z]\w*)>\s*$/,
+    end: /^\s*\/\/\s*<\/([A-Za-z]\w*)>\s*$/,
+  },
+  // Python: # region Name  ...  # endregion [Name]
+  {
+    start: /^\s*#\s*region\s+(.+?)\s*$/,
+    end: /^\s*#\s*endregion(?:\s+(.+?))?\s*$/,
+  },
+];
+
+/**
+ * Extract the code between region markers from a source file's content.
+ * Returns the trimmed code block or undefined if the region is not found.
+ */
+function extractRegion(
+  content: string,
+  regionName: string
+): string | undefined {
+  const lines = content.split(/\r?\n/);
+  let capturing = false;
+  let capturedLines: string[] = [];
+
+  for (const line of lines) {
+    if (capturing) {
+      // Check if this line is an end marker for our region
+      for (const pattern of REGION_PATTERNS) {
+        const endMatch = line.match(pattern.end);
+        if (endMatch && (!endMatch[1] || endMatch[1].trim() === regionName)) {
+          // Found end marker — return captured content
+          return trimIndentation(capturedLines);
+        }
+      }
+      // Skip nested region markers for the same region name
+      // (e.g. C# files may have both #region and // <Name> markers)
+      let isNestedMarker = false;
+      for (const pattern of REGION_PATTERNS) {
+        const startMatch = line.match(pattern.start);
+        if (startMatch && startMatch[1].trim() === regionName) {
+          isNestedMarker = true;
+          break;
+        }
+      }
+      if (!isNestedMarker) {
+        capturedLines.push(line);
+      }
+    } else {
+      // Check if this line is a start marker for our region
+      for (const pattern of REGION_PATTERNS) {
+        const startMatch = line.match(pattern.start);
+        if (startMatch && startMatch[1].trim() === regionName) {
+          capturing = true;
+          capturedLines = [];
+          break;
+        }
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Remove the common leading whitespace from all non-empty lines.
+ */
+function trimIndentation(lines: string[]): string {
+  const nonEmptyLines = lines.filter((l) => l.trim().length > 0);
+  if (nonEmptyLines.length === 0) return "";
+
+  const minIndent = Math.min(
+    ...nonEmptyLines.map((l) => {
+      const match = l.match(/^(\s*)/);
+      return match ? match[1].length : 0;
+    })
+  );
+
+  return lines
+    .map((l) => (l.trim().length === 0 ? "" : l.slice(minIndent)))
+    .join("\n")
+    .trim();
+}
+
+/**
+ * Convert a camelCase string to snake_case.
+ * e.g. "activateJobs" -> "activate_jobs"
+ */
+function camelToSnake(str: string): string {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+/**
+ * Build x-codeSamples entries for a given operationId from all configured SDK sources.
+ *
+ * @param operationId - The OpenAPI operationId to look up.
+ * @param sdkExamples - Array of SDK example source configurations.
+ * @param siteDir - The Docusaurus site root directory (for resolving relative paths).
+ * @param fileCache - Shared cache to avoid re-reading the same source files.
+ * @param mapCache - Shared cache for parsed operation-map.json files.
+ * @returns Array of x-codeSamples entries, or empty array if none found.
+ */
+export function buildCodeSamples(
+  operationId: string,
+  sdkExamples: SdkExampleSource[],
+  siteDir: string,
+  fileCache: Map<string, string>,
+  mapCache: Map<string, OperationMap>
+): { lang: string; label: string; source: string }[] {
+  const samples: { lang: string; label: string; source: string }[] = [];
+
+  for (const sdk of sdkExamples) {
+    const mapPath = path.resolve(siteDir, sdk.operationMapPath);
+    let operationMap = mapCache.get(mapPath);
+    if (!operationMap) {
+      if (!fs.existsSync(mapPath)) {
+        console.warn(`SDK examples: operation-map not found at ${mapPath}`);
+        continue;
+      }
+      operationMap = fs.readJSONSync(mapPath) as OperationMap;
+      mapCache.set(mapPath, operationMap);
+    }
+
+    // Try exact match first, then fall back to snake_case conversion
+    // (Python SDKs conventionally use snake_case operationIds)
+    const entries =
+      operationMap[operationId] || operationMap[camelToSnake(operationId)];
+    if (!entries || entries.length === 0) continue;
+
+    const mapDir = path.dirname(mapPath);
+
+    for (const entry of entries) {
+      const filePath = path.resolve(mapDir, entry.file);
+      let fileContent = fileCache.get(filePath);
+      if (fileContent === undefined) {
+        if (!fs.existsSync(filePath)) {
+          console.warn(
+            `SDK examples: source file not found at ${filePath} (referenced by ${sdk.lang} operation-map for ${operationId})`
+          );
+          continue;
+        }
+        fileContent = fs.readFileSync(filePath, "utf-8");
+        fileCache.set(filePath, fileContent);
+      }
+
+      const code = extractRegion(fileContent, entry.region);
+      if (!code) {
+        console.warn(
+          `SDK examples: region "${entry.region}" not found in ${filePath} (${sdk.lang}, ${operationId})`
+        );
+        continue;
+      }
+
+      samples.push({
+        lang: sdk.lang,
+        label: "SDK",
+        source: code,
+      });
+    }
+  }
+
+  return samples;
+}