Skip to navigation
API ReferencesCode exploration

Display SDK snippets

View as Markdown

If you use Fern to generate SDKs, you can display SDK code snippets in your API Reference. These snippets show examples using your actual SDK in TypeScript, Python, Go, and other supported languages.

Once configured, SDK snippets replace HTTP snippets.

Dynamic snippets

By default, SDK snippets are dynamic code examples that allow users to modify parameters and see code examples update in real time across all supported languages.

Alternatively, you can disable dynamic snippets in your docs.yml and use static code examples.

SDK code snippet selector

Configuration

Fern needs to read request examples from your API definition to generate code snippets. For OpenAPI, follow Swagger’s examples documentation.

Then follow the steps for the file you generate SDKs with.

With sdk-config.yml, 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.

1

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.

sdk-config.yml
sdkName: plant-store
docs:
  snippets:
    enabled: true
targets:
  - language: python
  - language: typescript
2

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.

docs.yml
navigation:
  - api: API Reference
    snippets:
      python:
        package: your-package-name
        version: 1.2.0
      typescript:
        package: your-package-name
        version: 1.2.0
3

Build the SDKs at that version

Run fern generate to build the SDKs with a new version 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.

4

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 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

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.

docs.yml
default-language: typescript
navigation:
  - api: API Reference
    snippets:
      python: your-package-name
      typescript: your-package-name

Endpoint request and response snippets

Looking for information on generating API endpoint request and response snippets? See our documentation on Endpoint Request Snippets and Endpoint Response Snippets.