From 5a35529c0a80174053f0b61f7815da23f3a4ca6c Mon Sep 17 00:00:00 2001 From: Nermina Date: Thu, 29 Oct 2026 20:32:56 +0000 Subject: [PATCH 1/7] docs: document SDK snippets from sdk-config.yml builds Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../pages/api-references/sdk-snippets.mdx | 54 ++++++++++++++++++- .../sdks/reference/sdk-config-reference.mdx | 14 ++++- 2 files changed, 66 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index a9b238e907..28ba8c6afa 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -20,7 +20,7 @@ Once configured, SDK snippets replace [HTTP snippets](/learn/docs/api-references ## Configuration -To configure SDK snippets, first name your SDKs in `generators.yml` and then reference that name in `docs.yml`. +To configure SDK snippets, first name your SDKs in `generators.yml` and then reference that name in `docs.yml`. If you generate SDKs with `sdk-config.yml`, [enable snippets in `sdk-config.yml`](#use-sdk-snippets-with-sdk-configyml) instead. @@ -134,6 +134,58 @@ Trigger your docs generation by running `fern generate --docs` locally or in CI/ +## Use SDK snippets with `sdk-config.yml` + +When you generate SDKs with [`sdk-config.yml`](/learn/sdks/reference/sdk-config), SDK generation saves a snippets file with each build. `fern generate --docs` reads that file and adds the snippets to your API Reference endpoints. This works for TypeScript, Python, Java, Go, Ruby, C#, and PHP SDKs. + + + +### Enable snippets in `sdk-config.yml` + +Set `docs.snippets.enabled` to `true` at the top level, where every target inherits it, or in a single target's `docs` block. Fern finds each SDK's build by its `sdkName`, so the target needs an `sdkName` of its own or the top-level one. + + +```yaml {1, 3-5} +sdkName: plant-store +docs: + snippets: + enabled: true +targets: + - language: python + - language: typescript +``` + + +### Generate the SDK + +Run `fern generate` to build the SDK. Fern reads snippets only from a successful build, and only from builds made after snippets were enabled. + +### Reference the SDK version in `docs.yml` + +Add a `snippets` entry for each language with the `version` of the SDK build to show. Fern uses the newest successful build of that language with a matching `sdkName` and version. + + +```yaml {4-9} +navigation: + - api: API Reference + snippets: + python: + package: your-package-name + version: 1.2.0 + typescript: + package: your-package-name + version: 1.2.0 +``` + + +### Trigger generation + +Run `fern generate --docs`. Snippets appear in the language dropdown on each endpoint. A [code sample you wrote](/learn/api-definitions/openapi/extensions/request-response-examples#code-samples) for an endpoint in the same language takes precedence over the generated snippet. + +If Fern can't find or read the snippets for a language, the CLI logs a warning and publishes the docs without them. + + + ## Additional options ### Specify SDK versions diff --git a/fern/products/sdks/reference/sdk-config-reference.mdx b/fern/products/sdks/reference/sdk-config-reference.mdx index e75bbdeffc..1cb9401e65 100644 --- a/fern/products/sdks/reference/sdk-config-reference.mdx +++ b/fern/products/sdks/reference/sdk-config-reference.mdx @@ -389,7 +389,7 @@ Optional package registry publication. `registry` selects the registry, and the README content and example configuration. - Standalone usage snippet generation. + Standalone usage snippet generation. Enabled snippets also appear in your docs' [API Reference](/learn/docs/api-references/sdk-snippets#use-sdk-snippets-with-sdk-configyml). The base URL used for links to generated API Reference files. @@ -398,6 +398,18 @@ Optional package registry publication. `registry` selects the registry, and the Whether API Reference documentation is included in the SDK output. +### `snippets` + + + Whether Fern saves a snippets file with each SDK build. `fern generate --docs` reads this file to show [SDK snippets in your API Reference](/learn/docs/api-references/sdk-snippets#use-sdk-snippets-with-sdk-configyml). + + + The format of the snippets file. + + + The path of the snippets file in the generated SDK. + + ## `generation` Generation settings inherited by every target. Each target's `generation` block also accepts language-specific settings, documented on each language's configuration page. From a4890d6e61d0b744389d5c84b0b8922bfc714baf Mon Sep 17 00:00:00 2001 From: Nermina Date: Thu, 29 Oct 2026 20:42:59 +0000 Subject: [PATCH 2/7] docs: align sdk-config snippets steps with developer instructions Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../docs/pages/api-references/sdk-snippets.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index 28ba8c6afa..095612fa59 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -156,16 +156,12 @@ targets: ``` -### Generate the SDK +### Add the SDK version to `docs.yml` -Run `fern generate` to build the SDK. Fern reads snippets only from a successful build, and only from builds made after snippets were enabled. - -### Reference the SDK version in `docs.yml` - -Add a `snippets` entry for each language with the `version` of the SDK build to show. Fern uses the newest successful build of that language with a matching `sdkName` and version. +Under your `api:` entry, add a `snippets` entry for each language you build, with the version you're about to build. List only the languages you build. -```yaml {4-9} +```yaml {3-9} navigation: - api: API Reference snippets: @@ -178,9 +174,13 @@ navigation: ``` +### Build the SDKs at that version + +Run `fern generate` to build the SDKs with a new [version](/learn/sdks/reference/sdk-config#sdkversion) that matches the `version` in `docs.yml`. Fern reads snippets only from a successful build made with snippets enabled, and uses the newest such build of each language with a matching `sdkName` and version. + ### Trigger generation -Run `fern generate --docs`. Snippets appear in the language dropdown on each endpoint. A [code sample you wrote](/learn/api-definitions/openapi/extensions/request-response-examples#code-samples) for an endpoint in the same language takes precedence over the generated snippet. +Run `fern generate --docs`. The output includes a line such as `Loaded SDK snippets (python: 12, typescript: 12)` with the number of endpoint snippets read for each language, and the snippets appear in the language dropdown on each endpoint. A [code sample you wrote](/learn/api-definitions/openapi/extensions/request-response-examples#code-samples) for an endpoint in the same language takes precedence over the generated snippet. If Fern can't find or read the snippets for a language, the CLI logs a warning and publishes the docs without them. From 299745f1429a795739ed70f919271f5747e83a45 Mon Sep 17 00:00:00 2001 From: Nermina Date: Thu, 29 Oct 2026 20:54:45 +0000 Subject: [PATCH 3/7] docs: note sdk-config.yml in snippet setup references Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/api-references/sdk-snippets.mdx | 2 +- fern/products/docs/pages/getting-started/project-structure.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index 095612fa59..443939f1b6 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -190,7 +190,7 @@ If Fern can't find or read the snippets for a language, the CLI logs a warning a ### Specify SDK versions -You can specify which SDK version to use when generating code snippets. +You can specify which SDK version to use when generating code snippets. If you generate SDKs with `sdk-config.yml`, `version` is required and must match the [version you build](#build-the-sdks-at-that-version). ```yaml {4-6} diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx index 781954cf6e..82cc3b63f6 100644 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ b/fern/products/docs/pages/getting-started/project-structure.mdx @@ -125,7 +125,7 @@ css: styles.css To generate [API Reference](/learn/docs/api-references/generate-api-ref) documentation, you need to provide your API definition. OpenAPI and AsyncAPI specs require a `generators.yml` file with an `api.specs` section. You can optionally add a `groups` section for SDK generation. -Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `generators.yml` to configure [SDK code snippets](/learn/docs/api-references/sdk-snippets) in your API Reference. +Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `generators.yml` or [`sdk-config.yml`](/learn/docs/api-references/sdk-snippets#use-sdk-snippets-with-sdk-configyml) to configure [SDK code snippets](/learn/docs/api-references/sdk-snippets) in your API Reference. From a9df2d307482c810d86cfba3252f89f99824af92 Mon Sep 17 00:00:00 2001 From: Nermina Date: Thu, 29 Oct 2026 21:01:42 +0000 Subject: [PATCH 4/7] docs: reflect sdk-config.yml and docs.yml specs on Docs project structure Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../getting-started/project-structure.mdx | 41 +++++++++++++++---- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx index 82cc3b63f6..9dde140abc 100644 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ b/fern/products/docs/pages/getting-started/project-structure.mdx @@ -20,7 +20,8 @@ The configuration files for your docs live in the `fern` folder: - + + @@ -62,7 +63,7 @@ The `assets` folder contains any images or videos used in your documentation. Yo The `docs.yml` file is the heart of your Fern documentation site. This configuration file controls your documentation's navigation structure, visual design, site functionality, and hosting settings. Only files referenced in your `docs.yml` navigation (or discovered via a [`folder` configuration](/learn/docs/configuration/navigation#add-a-folder)) are included in builds — any unreferenced files are ignored. -Fern treats `.yml` and `.yaml` extensions identically. This applies to all YAML files in a Fern project, including `docs.yml`, `generators.yml`, and API specification files. +Fern treats `.yml` and `.yaml` extensions identically. This applies to all YAML files in a Fern project, including `docs.yml`, `sdk-config.yml`, `generators.yml`, and API specification files. For complete configuration options, see the [`docs.yml` reference](/learn/docs/configuration/site-level-settings). @@ -121,17 +122,29 @@ css: styles.css ``` -## API definitions and `generators.yml` +## API definitions -To generate [API Reference](/learn/docs/api-references/generate-api-ref) documentation, you need to provide your API definition. OpenAPI and AsyncAPI specs require a `generators.yml` file with an `api.specs` section. You can optionally add a `groups` section for SDK generation. +To generate [API Reference](/learn/docs/api-references/generate-api-ref) documentation, you need to provide your API definition. List your spec files in the `specs` of an `api` entry in `docs.yml`, or in the `api.specs` section of a `generators.yml` file. When an `api` entry has `specs`, Fern [builds it from those files](/learn/docs/api-references/generate-api-ref#reference-a-spec-directly-from-docsyml) and ignores `generators.yml`. -Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `generators.yml` or [`sdk-config.yml`](/learn/docs/api-references/sdk-snippets#use-sdk-snippets-with-sdk-configyml) to configure [SDK code snippets](/learn/docs/api-references/sdk-snippets) in your API Reference. +SDKs are configured in [`sdk-config.yml`](/learn/sdks/reference/sdk-config). Projects that haven't [migrated to `sdk-config.yml`](/learn/sdks/legacy/generators/migration-guides/sdk-config) still configure SDKs in the `groups` section of `generators.yml`. + +Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `sdk-config.yml` or `generators.yml` to configure [SDK code snippets](/learn/docs/api-references/sdk-snippets) in your API Reference. Place your OpenAPI specification file in the `fern/` directory (or in a subfolder). Fern supports either YAML or JSON format. - Reference it in `generators.yml`: + Reference it in `docs.yml`: + + ```yaml title="docs.yml" + navigation: + - api: API Reference + specs: + - type: openapi + path: ./openapi.yml + ``` + + Or reference it in `generators.yml`: ```yaml title="generators.yml" api: @@ -143,7 +156,19 @@ To generate [API Reference](/learn/docs/api-references/generate-api-ref) documen - Place your AsyncAPI specification file in the `fern/` directory alongside your OpenAPI spec. Reference it in `generators.yml`: + Place your AsyncAPI specification file in the `fern/` directory alongside your OpenAPI spec. Reference it in `docs.yml`: + + ```yaml title="docs.yml" + navigation: + - api: API Reference + specs: + - type: openapi + path: ./openapi.yml + - type: asyncapi + path: ./asyncapi.yaml + ``` + + Or reference it in `generators.yml`: ```yaml title="generators.yml" api: @@ -173,7 +198,7 @@ To generate [API Reference](/learn/docs/api-references/generate-api-ref) documen - The `apis` folder must use this exact name. Reference each API in `docs.yml` using `api-name` that matches the subfolder name. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). + The `apis` folder must use this exact name. Reference each API in `docs.yml` using `api-name` that matches the subfolder name. If you list specs in `docs.yml` instead, add a separate `api` entry with its own `specs` for each API. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). From 1785c5a0ff3d7c68eaec77ea33d7df710fcc9229 Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 30 Oct 2026 14:26:25 +0000 Subject: [PATCH 5/7] docs: say Fern stores sdk-gen snippets server-side Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/api-references/sdk-snippets.mdx | 2 +- fern/products/sdks/reference/sdk-config-reference.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index 443939f1b6..26b52e7e84 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -136,7 +136,7 @@ Trigger your docs generation by running `fern generate --docs` locally or in CI/ ## Use SDK snippets with `sdk-config.yml` -When you generate SDKs with [`sdk-config.yml`](/learn/sdks/reference/sdk-config), SDK generation saves a snippets file with each build. `fern generate --docs` reads that file and adds the snippets to your API Reference endpoints. This works for TypeScript, Python, Java, Go, Ruby, C#, and PHP SDKs. +When you generate SDKs with [`sdk-config.yml`](/learn/sdks/reference/sdk-config), Fern stores the snippets from each SDK build on its servers. `fern generate --docs` fetches them and adds them to your API Reference endpoints. This works for TypeScript, Python, Java, Go, Ruby, C#, and PHP SDKs. diff --git a/fern/products/sdks/reference/sdk-config-reference.mdx b/fern/products/sdks/reference/sdk-config-reference.mdx index 1cb9401e65..bf7812bd0c 100644 --- a/fern/products/sdks/reference/sdk-config-reference.mdx +++ b/fern/products/sdks/reference/sdk-config-reference.mdx @@ -401,7 +401,7 @@ Optional package registry publication. `registry` selects the registry, and the ### `snippets` - Whether Fern saves a snippets file with each SDK build. `fern generate --docs` reads this file to show [SDK snippets in your API Reference](/learn/docs/api-references/sdk-snippets#use-sdk-snippets-with-sdk-configyml). + Whether Fern stores the snippets from each SDK build on its servers. `fern generate --docs` fetches them to show [SDK snippets in your API Reference](/learn/docs/api-references/sdk-snippets#use-sdk-snippets-with-sdk-configyml). The format of the snippets file. From 6793edb7848e3495e66960a992e5151a06fb04a6 Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 30 Oct 2026 20:08:41 +0000 Subject: [PATCH 6/7] docs: put sdk-config.yml and generators.yml snippet setup in tabs; move project structure to its own PR Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../pages/api-references/sdk-snippets.mdx | 123 +++++++++--------- .../getting-started/project-structure.mdx | 41 ++---- .../sdks/reference/sdk-config-reference.mdx | 4 +- 3 files changed, 74 insertions(+), 94 deletions(-) diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index 26b52e7e84..c05435b758 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -20,13 +20,67 @@ Once configured, SDK snippets replace [HTTP snippets](/learn/docs/api-references ## Configuration -To configure SDK snippets, first name your SDKs in `generators.yml` and then reference that name in `docs.yml`. If you generate SDKs with `sdk-config.yml`, [enable snippets in `sdk-config.yml`](#use-sdk-snippets-with-sdk-configyml) instead. +Fern needs to read request examples from your API definition to generate code snippets. For OpenAPI, follow [Swagger's examples documentation](https://swagger.io/docs/specification/adding-examples/). + +Then follow the steps for the file you generate SDKs with. + + + + +With [`sdk-config.yml`](/learn/sdks/reference/sdk-config), Fern stores the snippets from each SDK build on its servers. `fern generate --docs` fetches them and adds them to your API Reference endpoints. This works for TypeScript, Python, Java, Go, Ruby, C#, and PHP SDKs. -### Add examples to your API definition +### Enable snippets in `sdk-config.yml` -Fern needs to read request examples from your API definition to generate code snippets. For OpenAPI, follow [Swagger's examples documentation](https://swagger.io/docs/specification/adding-examples/). +Set `docs.snippets.enabled` to `true` at the top level, where every target inherits it, or in a single target's `docs` block. Fern finds each SDK's build by its `sdkName`, so the target needs an `sdkName` of its own or the top-level one. + + +```yaml {1, 3-5} +sdkName: plant-store +docs: + snippets: + enabled: true +targets: + - language: python + - language: typescript +``` + + +### Add the SDK version to `docs.yml` + +Under your `api:` entry, add a `snippets` entry for each language you build, with the version you're about to build. List only the languages you build. + + +```yaml {3-9} +navigation: + - api: API Reference + snippets: + python: + package: your-package-name + version: 1.2.0 + typescript: + package: your-package-name + version: 1.2.0 +``` + + +### Build the SDKs at that version + +Run `fern generate` to build the SDKs with a new [version](/learn/sdks/reference/sdk-config#sdkversion) that matches the `version` in `docs.yml`. Fern reads snippets only from a successful build made with snippets enabled, and uses the newest such build of each language with a matching `sdkName` and version. + +### Generate the docs + +Run `fern generate --docs`. The output includes a line such as `Loaded SDK snippets (python: 12, typescript: 12)` with the number of endpoint snippets read for each language, and the snippets appear in the language dropdown on each endpoint. A [code sample you wrote](/learn/api-definitions/openapi/extensions/request-response-examples#code-samples) for an endpoint in the same language takes precedence over the generated snippet. + +If Fern can't find or read the snippets for a language, the CLI logs a warning and publishes the docs without them. + + + + + + + ### Define a package name for your SDK(s) @@ -134,63 +188,9 @@ Trigger your docs generation by running `fern generate --docs` locally or in CI/ -## Use SDK snippets with `sdk-config.yml` - -When you generate SDKs with [`sdk-config.yml`](/learn/sdks/reference/sdk-config), Fern stores the snippets from each SDK build on its servers. `fern generate --docs` fetches them and adds them to your API Reference endpoints. This works for TypeScript, Python, Java, Go, Ruby, C#, and PHP SDKs. - - - -### Enable snippets in `sdk-config.yml` - -Set `docs.snippets.enabled` to `true` at the top level, where every target inherits it, or in a single target's `docs` block. Fern finds each SDK's build by its `sdkName`, so the target needs an `sdkName` of its own or the top-level one. - - -```yaml {1, 3-5} -sdkName: plant-store -docs: - snippets: - enabled: true -targets: - - language: python - - language: typescript -``` - - -### Add the SDK version to `docs.yml` - -Under your `api:` entry, add a `snippets` entry for each language you build, with the version you're about to build. List only the languages you build. - - -```yaml {3-9} -navigation: - - api: API Reference - snippets: - python: - package: your-package-name - version: 1.2.0 - typescript: - package: your-package-name - version: 1.2.0 -``` - - -### Build the SDKs at that version - -Run `fern generate` to build the SDKs with a new [version](/learn/sdks/reference/sdk-config#sdkversion) that matches the `version` in `docs.yml`. Fern reads snippets only from a successful build made with snippets enabled, and uses the newest such build of each language with a matching `sdkName` and version. - -### Trigger generation - -Run `fern generate --docs`. The output includes a line such as `Loaded SDK snippets (python: 12, typescript: 12)` with the number of endpoint snippets read for each language, and the snippets appear in the language dropdown on each endpoint. A [code sample you wrote](/learn/api-definitions/openapi/extensions/request-response-examples#code-samples) for an endpoint in the same language takes precedence over the generated snippet. - -If Fern can't find or read the snippets for a language, the CLI logs a warning and publishes the docs without them. - - - -## Additional options - -### Specify SDK versions +#### Specify SDK versions -You can specify which SDK version to use when generating code snippets. If you generate SDKs with `sdk-config.yml`, `version` is required and must match the [version you build](#build-the-sdks-at-that-version). +You can specify which SDK version to use when generating code snippets. ```yaml {4-6} @@ -203,6 +203,11 @@ navigation: ``` + + + +## Additional options + ### Set default snippet language Use the `default-language` key at the top indentation level of `docs.yml`. This setting applies to both SDK snippets and HTTP snippets. diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx index 9dde140abc..781954cf6e 100644 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ b/fern/products/docs/pages/getting-started/project-structure.mdx @@ -20,8 +20,7 @@ The configuration files for your docs live in the `fern` folder: - - + @@ -63,7 +62,7 @@ The `assets` folder contains any images or videos used in your documentation. Yo The `docs.yml` file is the heart of your Fern documentation site. This configuration file controls your documentation's navigation structure, visual design, site functionality, and hosting settings. Only files referenced in your `docs.yml` navigation (or discovered via a [`folder` configuration](/learn/docs/configuration/navigation#add-a-folder)) are included in builds — any unreferenced files are ignored. -Fern treats `.yml` and `.yaml` extensions identically. This applies to all YAML files in a Fern project, including `docs.yml`, `sdk-config.yml`, `generators.yml`, and API specification files. +Fern treats `.yml` and `.yaml` extensions identically. This applies to all YAML files in a Fern project, including `docs.yml`, `generators.yml`, and API specification files. For complete configuration options, see the [`docs.yml` reference](/learn/docs/configuration/site-level-settings). @@ -122,29 +121,17 @@ css: styles.css ``` -## API definitions +## API definitions and `generators.yml` -To generate [API Reference](/learn/docs/api-references/generate-api-ref) documentation, you need to provide your API definition. List your spec files in the `specs` of an `api` entry in `docs.yml`, or in the `api.specs` section of a `generators.yml` file. When an `api` entry has `specs`, Fern [builds it from those files](/learn/docs/api-references/generate-api-ref#reference-a-spec-directly-from-docsyml) and ignores `generators.yml`. +To generate [API Reference](/learn/docs/api-references/generate-api-ref) documentation, you need to provide your API definition. OpenAPI and AsyncAPI specs require a `generators.yml` file with an `api.specs` section. You can optionally add a `groups` section for SDK generation. -SDKs are configured in [`sdk-config.yml`](/learn/sdks/reference/sdk-config). Projects that haven't [migrated to `sdk-config.yml`](/learn/sdks/legacy/generators/migration-guides/sdk-config) still configure SDKs in the `groups` section of `generators.yml`. - -Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `sdk-config.yml` or `generators.yml` to configure [SDK code snippets](/learn/docs/api-references/sdk-snippets) in your API Reference. +Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `generators.yml` to configure [SDK code snippets](/learn/docs/api-references/sdk-snippets) in your API Reference. Place your OpenAPI specification file in the `fern/` directory (or in a subfolder). Fern supports either YAML or JSON format. - Reference it in `docs.yml`: - - ```yaml title="docs.yml" - navigation: - - api: API Reference - specs: - - type: openapi - path: ./openapi.yml - ``` - - Or reference it in `generators.yml`: + Reference it in `generators.yml`: ```yaml title="generators.yml" api: @@ -156,19 +143,7 @@ SDKs are configured in [`sdk-config.yml`](/learn/sdks/reference/sdk-config). Pro - Place your AsyncAPI specification file in the `fern/` directory alongside your OpenAPI spec. Reference it in `docs.yml`: - - ```yaml title="docs.yml" - navigation: - - api: API Reference - specs: - - type: openapi - path: ./openapi.yml - - type: asyncapi - path: ./asyncapi.yaml - ``` - - Or reference it in `generators.yml`: + Place your AsyncAPI specification file in the `fern/` directory alongside your OpenAPI spec. Reference it in `generators.yml`: ```yaml title="generators.yml" api: @@ -198,7 +173,7 @@ SDKs are configured in [`sdk-config.yml`](/learn/sdks/reference/sdk-config). Pro - The `apis` folder must use this exact name. Reference each API in `docs.yml` using `api-name` that matches the subfolder name. If you list specs in `docs.yml` instead, add a separate `api` entry with its own `specs` for each API. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). + The `apis` folder must use this exact name. Reference each API in `docs.yml` using `api-name` that matches the subfolder name. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). diff --git a/fern/products/sdks/reference/sdk-config-reference.mdx b/fern/products/sdks/reference/sdk-config-reference.mdx index bf7812bd0c..ae73863d32 100644 --- a/fern/products/sdks/reference/sdk-config-reference.mdx +++ b/fern/products/sdks/reference/sdk-config-reference.mdx @@ -389,7 +389,7 @@ Optional package registry publication. `registry` selects the registry, and the README content and example configuration. - Standalone usage snippet generation. Enabled snippets also appear in your docs' [API Reference](/learn/docs/api-references/sdk-snippets#use-sdk-snippets-with-sdk-configyml). + Standalone usage snippet generation. Enabled snippets also appear in your docs' [API Reference](/learn/docs/api-references/sdk-snippets#enable-snippets-in-sdk-configyml). The base URL used for links to generated API Reference files. @@ -401,7 +401,7 @@ Optional package registry publication. `registry` selects the registry, and the ### `snippets` - Whether Fern stores the snippets from each SDK build on its servers. `fern generate --docs` fetches them to show [SDK snippets in your API Reference](/learn/docs/api-references/sdk-snippets#use-sdk-snippets-with-sdk-configyml). + Whether Fern stores the snippets from each SDK build on its servers. `fern generate --docs` fetches them to show [SDK snippets in your API Reference](/learn/docs/api-references/sdk-snippets#enable-snippets-in-sdk-configyml). The format of the snippets file. From 62bedb5dab0dc3b9eff6058d88606f87dc0ae365 Mon Sep 17 00:00:00 2001 From: Nermina Date: Mon, 2 Nov 2026 17:55:36 +0000 Subject: [PATCH 7/7] docs: state minimum CLI version for sdk-gen snippets Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/api-references/sdk-snippets.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index c05435b758..a9b5886f6c 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -29,6 +29,8 @@ Then follow the steps for the file you generate SDKs with. With [`sdk-config.yml`](/learn/sdks/reference/sdk-config), Fern stores the snippets from each SDK build on its servers. `fern generate --docs` fetches them and adds them to your API Reference endpoints. This works for TypeScript, Python, Java, Go, Ruby, C#, and PHP SDKs. +Requires Fern CLI version `5.188.0` or later. Run `fern upgrade` to update. + ### Enable snippets in `sdk-config.yml`