fix(theme): support multiple x-codeSamples per language (#1204)

Allow multiple x-codeSamples entries that share the same `lang` to render
as distinct inner tabs disambiguated by their `label`. Previously this
crashed with `Duplicate values "Python, Python" found in <Tabs>` because
`mergeCodeSampleLanguage` used `lang` as the per-sample identity, and the
inner CodeTab's `value` and React `key` collided.

- Build a unique id per sample (`${lang}-${label}` or `${lang}-${index}`)
  with a defensive collision suffix so duplicate-label specs render two
  visually identical tabs instead of crashing.
- Fix two stale-key bugs in CodeSnippets/index.tsx (`lang.sample` and
  `lang.variant` used singular defaults inside `.map` iterations).
- Reset `selectedSample` when the active language changes so the inner
  tab strip falls back to the new language's first sample.
- Add `themeConfig.api.hideGeneratedSnippets` (default `false`,
  opt-in) to suppress Postman-generated snippets per-operation,
  per-language whenever `x-codeSamples` are provided for that language
  on that operation. Closes #1036 for users who opt in.
- Add unit tests for `mergeCodeSampleLanguage` covering single-sample,
  multi-sample with/without labels, and duplicate-label collision.
- Expand the demo `petstore.yaml` x-codeSamples fixture to exercise all
  five paths.
- Document multi-sample usage and the new flag in vendor-extensions.mdx.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: sserrata

demo/docs/vendor-extensions.mdx

@@ -22,3 +22,46 @@ The OpenAPI plugin and theme recognize several [vendor extensions](https://swagg
 | `x-enumDescription` / `x-enumDescriptions` | Document individual enum values. |
 
 Other ReDoc extensions such as `x-circular-ref`, `x-code-samples` (deprecated), `x-examples`, `x-ignoredHeaderParameters`, `x-nullable`, `x-servers`, `x-traitTag`, `x-additionalPropertiesName`, and `x-explicitMappingOnly` are detected but ignored when extracting custom extensions.
+
+## `x-codeSamples`
+
+`x-codeSamples` attaches one or more author-written code snippets to an operation. Each entry has a `lang`, an optional `label`, and a `source`. The plugin renders one outer tab per language and one inner tab per sample within that language.
+
+### Multiple samples per language
+
+Authors often want to show several variants of the same language — for example, three Python snippets covering different authentication flows. Provide a distinct `label` on each entry to disambiguate the inner tabs:
+
+```yaml
+x-codeSamples:
+  - lang: Python
+    label: KeyPair Auth
+    source: |
+      # ...
+  - lang: Python
+    label: Basic Auth
+    source: |
+      # ...
+  - lang: Python
+    label: OAuth
+    source: |
+      # ...
+```
+
+If `label` is omitted on entries that share a `lang`, the inner tabs fall back to indexed identifiers (`Python-0`, `Python-1`, …) and will display the bare language name on each tab. Adding a `label` is recommended whenever a language appears more than once.
+
+If two entries share both the same `lang` and the same `label`, the page still renders — a numeric suffix is appended internally to keep tab identifiers unique — but the visible labels will be identical. Use unique labels to avoid reader confusion.
+
+### Hiding generated snippets when custom samples exist
+
+By default, custom `x-codeSamples` and the Postman-generated snippets (HTTP, cURL, language variants, etc.) render side by side inside each language tab. Set `themeConfig.api.hideGeneratedSnippets` to `true` to suppress the generated block on a per-operation, per-language basis whenever `x-codeSamples` are provided for that language:
+
+```ts
+// docusaurus.config.ts
+themeConfig: {
+  api: {
+    hideGeneratedSnippets: true,
+  },
+}
+```
+
+Languages without any custom samples on a given operation continue to show the generated snippets normally. The default is `false`, which preserves existing behavior.

demo/examples/petstore.yaml

@@ -197,6 +197,7 @@ paths:
         - OpenID: []
 
       x-codeSamples:
+        # Single sample, no label (existing case — fallback id is "C#-0")
         - lang: "C#"
           source: |
             PetStore.v1.Pet pet = new PetStore.v1.Pet();
@@ -214,6 +215,7 @@ paths:
               // Something wrong -- check response for errors
               Console.WriteLine(response.getRawResponse());
             }
+        # Single sample, with label (existing case — id is "PHP-Custom")
         - lang: PHP
           label: Custom
           source: |
@@ -226,6 +228,75 @@ paths:
             } catch (UnprocessableEntityException $e) {
                 var_dump($e->getErrors());
             }
+        # Multiple samples for the same language, each with a distinct label
+        # (issue #1204). Inner tabs render as KeyPair Auth / Basic Auth / OAuth.
+        - lang: Python
+          label: KeyPair Auth
+          source: |
+            import requests
+            from cryptography.hazmat.primitives.serialization import load_pem_private_key
+
+            with open("private_key.pem", "rb") as f:
+                key = load_pem_private_key(f.read(), password=None)
+            token = sign_jwt(key)  # implementation-specific
+            requests.post(
+                "https://example.com/v1/pet",
+                headers={"Authorization": f"Bearer {token}"},
+                json={"name": "Rex", "photoUrls": []},
+            )
+        - lang: Python
+          label: Basic Auth
+          source: |
+            import requests
+            from requests.auth import HTTPBasicAuth
+
+            requests.post(
+                "https://example.com/v1/pet",
+                auth=HTTPBasicAuth("user", "password"),
+                json={"name": "Rex", "photoUrls": []},
+            )
+        - lang: Python
+          label: OAuth
+          source: |
+            import requests
+            from requests_oauthlib import OAuth2Session
+
+            oauth = OAuth2Session(client_id, token=token)
+            oauth.post(
+                "https://example.com/v1/pet",
+                json={"name": "Rex", "photoUrls": []},
+            )
+        # Multiple samples for the same language with NO labels
+        # (defensive indexed-id fallback — ids are PowerShell-7 and PowerShell-8).
+        - lang: PowerShell
+          source: |
+            $pet = @{ name = "Rex"; photoUrls = @() } | ConvertTo-Json
+            Invoke-RestMethod -Uri https://example.com/v1/pet -Method Post -Body $pet -ContentType application/json
+        - lang: PowerShell
+          source: |
+            $headers = @{ Authorization = "Bearer $token" }
+            $pet = @{ name = "Rex"; photoUrls = @() } | ConvertTo-Json
+            Invoke-RestMethod -Uri https://example.com/v1/pet -Method Post -Headers $headers -Body $pet -ContentType application/json
+        # Two samples sharing the same lang AND label (author bug — defensive
+        # collision suffix keeps the page rendering instead of crashing).
+        - lang: Java
+          label: Auth
+          source: |
+            // OkHttp + bearer token
+            Request request = new Request.Builder()
+                .url("https://example.com/v1/pet")
+                .header("Authorization", "Bearer " + token)
+                .post(RequestBody.create(json, JSON))
+                .build();
+        - lang: Java
+          label: Auth
+          source: |
+            // HttpClient (JDK 11+) with basic auth
+            HttpRequest request = HttpRequest.newBuilder()
+                .uri(URI.create("https://example.com/v1/pet"))
+                .header("Authorization", "Basic " + encoded)
+                .POST(BodyPublishers.ofString(json))
+                .build();
       requestBody:
         $ref: "#/components/requestBodies/Pet"
     put:

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/CodeSnippets/index.tsx

@@ -17,6 +17,8 @@ import cloneDeep from "lodash/cloneDeep";
 import codegen from "postman-code-generators";
 import * as sdk from "postman-collection";
 
+import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
+
 import { CodeSample, Language } from "./code-snippets-types";
 import {
   getCodeSampleSourceFromLanguage,
@@ -114,6 +116,10 @@ function CodeSnippets({
     encoding,
   });
 
+  const themeConfig = siteConfig.themeConfig as ThemeConfig;
+  const hideGeneratedSnippets =
+    themeConfig?.api?.hideGeneratedSnippets ?? false;
+
   // User-defined languages array
   // Can override languageSet, change order of langs, override options and variants
   const userDefinedLanguageSet =
@@ -153,6 +159,14 @@ function CodeSnippets({
     getCodeSampleSourceFromLanguage(language)
   );
 
+  // Reset selectedSample whenever the active language changes so the inner
+  // tab strip falls back to its first sample instead of trying to match an
+  // id that belongs to a different language's samples.
+  useEffect(() => {
+    setSelectedSample(language?.samples?.[0]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [language?.language]);
+
   useEffect(() => {
     if (language && !!language.sample) {
       setCodeSampleCodeText(getCodeSampleSourceFromLanguage(language));
@@ -295,7 +309,7 @@ function CodeSnippets({
                             ? lang.samplesLabels[index]
                             : sample
                         }
-                        key={`${lang.language}-${lang.sample}`}
+                        key={`${lang.language}-${sample}`}
                         attributes={{
                           className: `openapi-tabs__code-item--sample`,
                         }}
@@ -315,40 +329,42 @@ function CodeSnippets({
               )}
 
               {/* Inner generated code snippets */}
-              <CodeTabs
-                className="openapi-tabs__code-container-inner"
-                action={{
-                  setLanguage: setLanguage,
-                  setSelectedVariant: setSelectedVariant,
-                }}
-                includeVariant={true}
-                currentLanguage={lang}
-                defaultValue={selectedVariant}
-                languageSet={mergedLangs}
-                lazy
-              >
-                {lang.variants.map((variant, index) => {
-                  return (
-                    <CodeTab
-                      value={variant.toLowerCase()}
-                      label={variant.toUpperCase()}
-                      key={`${lang.language}-${lang.variant}`}
-                      attributes={{
-                        className: `openapi-tabs__code-item--variant`,
-                      }}
-                    >
-                      {/* @ts-ignore */}
-                      <ApiCodeBlock
-                        language={lang.highlight}
-                        className="openapi-explorer__code-block"
-                        showLineNumbers={true}
+              {!(hideGeneratedSnippets && lang.samples?.length) && (
+                <CodeTabs
+                  className="openapi-tabs__code-container-inner"
+                  action={{
+                    setLanguage: setLanguage,
+                    setSelectedVariant: setSelectedVariant,
+                  }}
+                  includeVariant={true}
+                  currentLanguage={lang}
+                  defaultValue={selectedVariant}
+                  languageSet={mergedLangs}
+                  lazy
+                >
+                  {lang.variants.map((variant, index) => {
+                    return (
+                      <CodeTab
+                        value={variant.toLowerCase()}
+                        label={variant.toUpperCase()}
+                        key={`${lang.language}-${variant}`}
+                        attributes={{
+                          className: `openapi-tabs__code-item--variant`,
+                        }}
                       >
-                        {codeText}
-                      </ApiCodeBlock>
-                    </CodeTab>
-                  );
-                })}
-              </CodeTabs>
+                        {/* @ts-ignore */}
+                        <ApiCodeBlock
+                          language={lang.highlight}
+                          className="openapi-explorer__code-block"
+                          showLineNumbers={true}
+                        >
+                          {codeText}
+                        </ApiCodeBlock>
+                      </CodeTab>
+                    );
+                  })}
+                </CodeTabs>
+              )}
             </CodeTab>
           );
         })}

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/CodeSnippets/languages.test.ts

@@ -0,0 +1,109 @@
+/* ============================================================================
+ * 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 { CodeSample, Language } from "./code-snippets-types";
+import { mergeCodeSampleLanguage } from "./languages";
+
+const baseLang = (
+  language: string,
+  codeSampleLanguage: Language["codeSampleLanguage"]
+): Language => ({
+  highlight: language,
+  language,
+  codeSampleLanguage,
+  logoClass: language,
+  variant: "http",
+  variants: ["http"],
+});
+
+describe("mergeCodeSampleLanguage", () => {
+  it("returns the language unchanged when no codeSamples target it", () => {
+    const langs = [baseLang("python", "Python")];
+    const result = mergeCodeSampleLanguage(langs, []);
+    expect(result[0]).toEqual(langs[0]);
+    expect(result[0].samples).toBeUndefined();
+  });
+
+  it("attaches a single sample with no label using an indexed id", () => {
+    const samples: CodeSample[] = [{ lang: "Python", source: "print('hi')" }];
+    const [py] = mergeCodeSampleLanguage(
+      [baseLang("python", "Python")],
+      samples
+    );
+    expect(py.samples).toEqual(["Python-0"]);
+    expect(py.samplesLabels).toEqual(["Python"]);
+    expect(py.samplesSources).toEqual(["print('hi')"]);
+    expect(py.sample).toBe("Python-0");
+  });
+
+  it("attaches a single sample with a label using lang-label id", () => {
+    const samples: CodeSample[] = [
+      { lang: "PHP", label: "Custom", source: "<?php" },
+    ];
+    const [php] = mergeCodeSampleLanguage([baseLang("php", "PHP")], samples);
+    expect(php.samples).toEqual(["PHP-Custom"]);
+    expect(php.samplesLabels).toEqual(["Custom"]);
+  });
+
+  it("produces unique ids for multiple samples sharing a lang with distinct labels (#1204)", () => {
+    const samples: CodeSample[] = [
+      { lang: "Python", label: "KeyPair Auth", source: "a" },
+      { lang: "Python", label: "Basic Auth", source: "b" },
+      { lang: "Python", label: "OAuth", source: "c" },
+    ];
+    const [py] = mergeCodeSampleLanguage(
+      [baseLang("python", "Python")],
+      samples
+    );
+    expect(py.samples).toEqual([
+      "Python-KeyPair Auth",
+      "Python-Basic Auth",
+      "Python-OAuth",
+    ]);
+    expect(new Set(py.samples).size).toBe(3);
+    expect(py.samplesLabels).toEqual(["KeyPair Auth", "Basic Auth", "OAuth"]);
+    expect(py.samplesSources).toEqual(["a", "b", "c"]);
+  });
+
+  it("produces unique indexed ids for multiple samples sharing a lang without labels", () => {
+    const samples: CodeSample[] = [
+      { lang: "PowerShell", source: "x" },
+      { lang: "PowerShell", source: "y" },
+    ];
+    const [ps] = mergeCodeSampleLanguage(
+      [baseLang("powershell", "PowerShell")],
+      samples
+    );
+    expect(ps.samples).toEqual(["PowerShell-0", "PowerShell-1"]);
+    expect(new Set(ps.samples).size).toBe(2);
+    expect(ps.samplesLabels).toEqual(["PowerShell", "PowerShell"]);
+  });
+
+  it("defensively suffixes ids when lang+label collides", () => {
+    const samples: CodeSample[] = [
+      { lang: "Java", label: "Auth", source: "a" },
+      { lang: "Java", label: "Auth", source: "b" },
+    ];
+    const [java] = mergeCodeSampleLanguage([baseLang("java", "Java")], samples);
+    expect(java.samples).toEqual(["Java-Auth", "Java-Auth-1"]);
+    expect(new Set(java.samples).size).toBe(2);
+    expect(java.samplesLabels).toEqual(["Auth", "Auth"]);
+  });
+
+  it("filters codeSamples by codeSampleLanguage and leaves other languages alone", () => {
+    const samples: CodeSample[] = [
+      { lang: "Python", label: "A", source: "a" },
+      { lang: "Java", label: "B", source: "b" },
+    ];
+    const result = mergeCodeSampleLanguage(
+      [baseLang("python", "Python"), baseLang("php", "PHP")],
+      samples
+    );
+    expect(result[0].samples).toEqual(["Python-A"]);
+    expect(result[1].samples).toBeUndefined();
+  });
+});

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/CodeSnippets/languages.ts

@@ -22,12 +22,24 @@ export function mergeCodeSampleLanguage(
     );
 
     if (languageCodeSamples.length) {
-      const samples = languageCodeSamples.map(({ lang }) => lang);
       const samplesLabels = languageCodeSamples.map(
         ({ label, lang }) => label || lang
       );
       const samplesSources = languageCodeSamples.map(({ source }) => source);
 
+      // Build a unique id per sample for use as the inner Tab's `value`.
+      // Prefer `${lang}-${label}`; fall back to `${lang}-${index}` when no
+      // label is provided. Defensively suffix with `-${index}` on collision
+      // so duplicate-label specs render two visually identical tabs instead
+      // of crashing Docusaurus's unique-value check.
+      const seen = new Set<string>();
+      const samples = languageCodeSamples.map((cs, i) => {
+        const base = cs.label ? `${cs.lang}-${cs.label}` : `${cs.lang}-${i}`;
+        const id = seen.has(base) ? `${base}-${i}` : base;
+        seen.add(id);
+        return id;
+      });
+
       return {
         ...language,
         sample: samples[0],