From a0cb38d97c68ad0c7db78ae3a7711505afa9923c Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 10 Jun 2026 02:23:19 +0000
Subject: [PATCH] docs: document both sdk and language variants for
 code-samples in x-fern-examples

Co-Authored-By: bot_apk <apk@cognition.ai>
---
 .../api-def/openapi/extensions/examples.mdx   | 32 +++++++++++++++++++
 .../api-def/openapi/extensions/examples.mdx   | 32 +++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/fern/products/api-def/openapi/extensions/examples.mdx b/fern/products/api-def/openapi/extensions/examples.mdx
index de2909977..52d80bc0a 100644
--- a/fern/products/api-def/openapi/extensions/examples.mdx
+++ b/fern/products/api-def/openapi/extensions/examples.mdx
@@ -64,6 +64,15 @@ paths:
 
 Fern generators automatically add SDK code samples. To specify custom code samples for an example, use `code-samples`.
 
+Each code sample uses one of two keys to identify the language:
+
+| Key | Value | Use when |
+|-----|-------|----------|
+| `sdk` | One of the supported SDK languages: `curl`, `python`, `javascript`, `typescript`, `go`, `ruby`, `csharp`, `java`, `js`, `node`, `ts`, `nodets`, `golang`, `dotnet`, `jvm`, `c#` | The sample maps to a Fern-supported SDK language tab |
+| `language` | Any string | The sample is for a language not in the supported list, or you want to include an `install` command |
+
+Using `sdk`:
+
 ```yaml title="openapi.yml" {11-16}
 paths:
   /users/{userId}:
@@ -83,6 +92,29 @@ paths:
                 client.users.get("user-1234")
 ```
 
+Using `language`:
+
+```yaml title="openapi.yml" {11-18}
+paths:
+  /users/{userId}:
+    get:
+      x-fern-examples:
+        - path-parameters:
+            userId: user-1234
+          response:
+            body:
+              name: Foo
+              ssn: 1234
+          code-samples:
+            - language: php
+              install: composer require acme/sdk
+              code: |
+                use Acme\Client;
+
+                $client = new Client();
+                $client->users->get("user-1234");
+```
+
 ## Convert to native OpenAPI examples
 
 To make `x-fern-examples` work with non-Fern OpenAPI tools, run [`fern api enrich`](/learn/cli-api-reference/cli-reference/commands#fern-api-enrich) to convert them into native OpenAPI example fields.
diff --git a/fern/translations/zh/products/api-def/openapi/extensions/examples.mdx b/fern/translations/zh/products/api-def/openapi/extensions/examples.mdx
index 6e894bc5e..34b37d95b 100644
--- a/fern/translations/zh/products/api-def/openapi/extensions/examples.mdx
+++ b/fern/translations/zh/products/api-def/openapi/extensions/examples.mdx
@@ -62,6 +62,15 @@ paths:
 
 Fern 生成器会自动添加 SDK 代码示例。如果您想为示例指定自定义代码示例，请使用 `code-samples`。
 
+每个代码示例使用以下两个键之一来标识语言：
+
+| 键 | 值 | 使用场景 |
+|-----|-------|----------|
+| `sdk` | 支持的 SDK 语言之一：`curl`、`python`、`javascript`、`typescript`、`go`、`ruby`、`csharp`、`java`、`js`、`node`、`ts`、`nodets`、`golang`、`dotnet`、`jvm`、`c#` | 代码示例对应 Fern 支持的 SDK 语言标签 |
+| `language` | 任意字符串 | 代码示例的语言不在支持列表中，或您需要包含 `install` 命令 |
+
+使用 `sdk`：
+
 ```yaml title="openapi.yml" {11-16}
 paths:
   /users/{userId}:
@@ -79,4 +88,27 @@ paths:
                 import { UserClient } from "...";
 
                 client.users.get("user-1234")
+```
+
+使用 `language`：
+
+```yaml title="openapi.yml" {11-18}
+paths:
+  /users/{userId}:
+    get:
+      x-fern-examples:
+        - path-parameters:
+            userId: user-1234
+          response:
+            body:
+              name: Foo
+              ssn: 1234
+          code-samples:
+            - language: php
+              install: composer require acme/sdk
+              code: |
+                use Acme\Client;
+
+                $client = new Client();
+                $client->users->get("user-1234");
 ```
\ No newline at end of file