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 1/3] docs: document both sdk and language variants for code-samples in x-fern-examples Co-Authored-By: bot_apk --- .../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 de29099778..52d80bc0ae 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 6e894bc5ec..34b37d95b9 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 From 891d208cb5bc7ff1fcef889f102fb6247d2ee969 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 15 Jun 2026 15:55:10 -0400 Subject: [PATCH 2/3] improve structure --- .../api-def/openapi/extensions/examples.mdx | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/fern/products/api-def/openapi/extensions/examples.mdx b/fern/products/api-def/openapi/extensions/examples.mdx index 52d80bc0ae..95e58e3d4f 100644 --- a/fern/products/api-def/openapi/extensions/examples.mdx +++ b/fern/products/api-def/openapi/extensions/examples.mdx @@ -6,16 +6,16 @@ og:title: OpenAPI request + response examples --- - -Fern generates realistic examples automatically using [AI-generated examples](/learn/docs/ai-features/ai-examples), enabled by default. Use `x-fern-examples` to manually define specific example values. Manual examples take priority over AI-generated ones. You can also [disable AI examples entirely](/learn/docs/configuration/site-level-settings#ai-examplesenabled). - +Fern generates realistic examples automatically using [AI-generated examples](/learn/docs/ai-features/ai-examples), enabled by default. Use `x-fern-examples` to manually define specific values, associate request and response pairs that OpenAPI's separate example fields can't link, or define multiple named examples for an endpoint. -Use `x-fern-examples` to associate specific request and response pairs or define multiple named examples for an endpoint. OpenAPI has several example fields, but provides no way to link a request with its corresponding response. +Manual examples take priority over AI-generated ones, and you can [disable AI examples entirely](/learn/docs/configuration/site-level-settings#ai-examplesenabled). ## Structure `x-fern-examples` is an array. Each element can contain `path-parameters`, `query-parameters`, `headers`, `request`, and `response` values that are all associated. Optionally, add a `name` field to provide a descriptive label. +The `request` and `response` values use different shapes: + - `request` holds the request body properties directly. - `response` requires a nested `body` key containing the response body properties. @@ -32,8 +32,8 @@ paths: x-fern-examples: - name: Get user 1234 # Optional descriptive label headers: - custom_api_key: "capi_12345" # header defined using x-global-header extension - userpool_id: "pool_67890" # header defined using x-global-header extension + custom_api_key: "capi_12345" # header defined using x-fern-global-headers extension + userpool_id: "pool_67890" # header defined using x-fern-global-headers extension path-parameters: userId: user-1234 response: @@ -71,8 +71,8 @@ Each code sample uses one of two keys to identify the language: | `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}: @@ -91,9 +91,8 @@ paths: client.users.get("user-1234") ``` - -Using `language`: - + + ```yaml title="openapi.yml" {11-18} paths: /users/{userId}: @@ -114,6 +113,8 @@ paths: $client = new Client(); $client->users->get("user-1234"); ``` + + ## Convert to native OpenAPI examples From 830b2df11adb88d0acd47ead6182551466749e3e Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 15 Jun 2026 16:03:31 -0400 Subject: [PATCH 3/3] remove table --- fern/products/api-def/openapi/extensions/examples.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/fern/products/api-def/openapi/extensions/examples.mdx b/fern/products/api-def/openapi/extensions/examples.mdx index 95e58e3d4f..3f915df5fb 100644 --- a/fern/products/api-def/openapi/extensions/examples.mdx +++ b/fern/products/api-def/openapi/extensions/examples.mdx @@ -66,10 +66,8 @@ Fern generators automatically add SDK code samples. To specify custom code sampl 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 | +- `sdk` — for a language that maps to a Fern-supported SDK tab: `curl`, `python`, `javascript`, `typescript`, `go`, `ruby`, `csharp`, `java`, `js`, `node`, `ts`, `nodets`, `golang`, `dotnet`, `jvm`, `c#`. +- `language` — for any other language, or when you want to include an `install` command.