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

package/lib/openapi/sdkExamples.d.ts

@@ -16,6 +16,8 @@ interface OperationMapEntry {
     file: string;
     region: string;
     label?: string;
+    /** Import/using statement to prepend to the code sample (e.g. "import { CamundaClient } from ..."). */
+    imports?: string;
 }
 /**
  * Shape of operation-map.json: operationId -> entries[].

package/lib/openapi/sdkExamples.js

@@ -125,7 +125,13 @@ function buildCodeSamples(operationId, sdkExamples, siteDir, fileCache, mapCache
                 console.warn(`SDK examples: operation-map not found at ${mapPath}`);
                 continue;
             }
-            operationMap = fs_extra_1.default.readJSONSync(mapPath);
+            try {
+                operationMap = fs_extra_1.default.readJSONSync(mapPath);
+            }
+            catch (err) {
+                console.warn(`SDK examples: failed to parse ${mapPath}: ${err instanceof Error ? err.message : err}`);
+                continue;
+            }
             mapCache.set(mapPath, operationMap);
         }
         // Try exact match first, then fall back to snake_case conversion
@@ -134,6 +140,7 @@ function buildCodeSamples(operationId, sdkExamples, siteDir, fileCache, mapCache
         if (!entries || entries.length === 0)
             continue;
         const mapDir = path_1.default.dirname(mapPath);
+        const hasMultipleEntries = entries.length > 1;
         for (const entry of entries) {
             const filePath = path_1.default.resolve(mapDir, entry.file);
             let fileContent = fileCache.get(filePath);
@@ -150,10 +157,13 @@ function buildCodeSamples(operationId, sdkExamples, siteDir, fileCache, mapCache
                 console.warn(`SDK examples: region "${entry.region}" not found in ${filePath} (${sdk.lang}, ${operationId})`);
                 continue;
             }
+            // Use "SDK - <label>" only when there are multiple entries for the same
+            // operationId, so readers can distinguish between variants.
+            const label = hasMultipleEntries && entry.label ? `SDK - ${entry.label}` : "SDK";
             samples.push({
                 lang: sdk.lang,
-                label: "SDK",
-                source: code,
+                label,
+                source: entry.imports ? `${entry.imports}\n\n${code}` : code,
             });
         }
     }

package/package.json

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

package/src/openapi/sdkExamples.ts

@@ -28,6 +28,8 @@ interface OperationMapEntry {
   file: string;
   region: string;
   label?: string;
+  /** Import/using statement to prepend to the code sample (e.g. "import { CamundaClient } from ..."). */
+  imports?: string;
 }
 
 /**
@@ -169,7 +171,14 @@ export function buildCodeSamples(
         console.warn(`SDK examples: operation-map not found at ${mapPath}`);
         continue;
       }
-      operationMap = fs.readJSONSync(mapPath) as OperationMap;
+      try {
+        operationMap = fs.readJSONSync(mapPath) as OperationMap;
+      } catch (err) {
+        console.warn(
+          `SDK examples: failed to parse ${mapPath}: ${err instanceof Error ? err.message : err}`
+        );
+        continue;
+      }
       mapCache.set(mapPath, operationMap);
     }
 
@@ -180,6 +189,7 @@ export function buildCodeSamples(
     if (!entries || entries.length === 0) continue;
 
     const mapDir = path.dirname(mapPath);
+    const hasMultipleEntries = entries.length > 1;
 
     for (const entry of entries) {
       const filePath = path.resolve(mapDir, entry.file);
@@ -203,10 +213,15 @@ export function buildCodeSamples(
         continue;
       }
 
+      // Use "SDK - <label>" only when there are multiple entries for the same
+      // operationId, so readers can distinguish between variants.
+      const label =
+        hasMultipleEntries && entry.label ? `SDK - ${entry.label}` : "SDK";
+
       samples.push({
         lang: sdk.lang,
-        label: "SDK",
-        source: code,
+        label,
+        source: entry.imports ? `${entry.imports}\n\n${code}` : code,
       });
     }
   }