@camunda8/docusaurus-plugin-openapi-docs 4.5.4 → 4.6.1

package/lib/openapi/sdkExamples.d.ts

@@ -8,6 +8,9 @@ export interface SdkExampleSource {
     highlight?: string;
     /** Path to the operation-map.json file (relative to site root or absolute). */
     operationMapPath: string;
+    /** Default import/using statement prepended to every code sample for this language.
+     *  Individual entries in operation-map.json can override this with their own `imports` field. */
+    defaultImports?: string;
 }
 /**
  * A single entry in operation-map.json for one operationId.
@@ -16,6 +19,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

@@ -116,6 +116,7 @@ function camelToSnake(str) {
  * @returns Array of x-codeSamples entries, or empty array if none found.
  */
 function buildCodeSamples(operationId, sdkExamples, siteDir, fileCache, mapCache) {
+    var _a;
     const samples = [];
     for (const sdk of sdkExamples) {
         const mapPath = path_1.default.resolve(siteDir, sdk.operationMapPath);
@@ -140,6 +141,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);
@@ -156,10 +158,14 @@ 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";
+            const imports = (_a = entry.imports) !== null && _a !== void 0 ? _a : sdk.defaultImports;
             samples.push({
                 lang: sdk.lang,
-                label: "SDK",
-                source: code,
+                label,
+                source: imports ? `${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.4",
+  "version": "4.6.1",
   "license": "MIT",
   "keywords": [
     "openapi",

package/src/openapi/sdkExamples.ts

@@ -19,6 +19,9 @@ export interface SdkExampleSource {
   highlight?: string;
   /** Path to the operation-map.json file (relative to site root or absolute). */
   operationMapPath: string;
+  /** Default import/using statement prepended to every code sample for this language.
+   *  Individual entries in operation-map.json can override this with their own `imports` field. */
+  defaultImports?: string;
 }
 
 /**
@@ -28,6 +31,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;
 }
 
 /**
@@ -187,6 +192,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);
@@ -210,10 +216,16 @@ 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";
+
+      const imports = entry.imports ?? sdk.defaultImports;
       samples.push({
         lang: sdk.lang,
-        label: "SDK",
-        source: code,
+        label,
+        source: imports ? `${imports}\n\n${code}` : code,
       });
     }
   }