Display SDK snippets

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.

Configuration

To configure SDK snippets, first name your SDKs in generators.yml and then reference that name in docs.yml.

Add examples to your API definition

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

Define a package name for your SDK(s)

Configure package names in your generators.yml file:

For Python, TypeScript, Ruby, and .NET/C#, add package-name: your-package-name to the output section.
For Java, add coordinate: com.your-org:your-package-name to the output section.
For PHP, add packageName: YourPackageName to the config section.
For Go, add repository: your-organization/your-repository to the github section.

Fern supports SDK snippets for TypeScript, Python, Ruby, Go, Java, PHP, and .NET/C#. File an issue to request additional languages.

generators.yml

1 groups:
2   production:
3     generators:
4       - name: fernapi/fern-python-sdk
5         version: 5.10.0
6         output:
7           location: pypi
8           token: ${PYPI_TOKEN}
9           package-name: your-package-name # <--- add this field
10         ...
11       - name: fernapi/fern-typescript-sdk
12         version: 3.69.0
13         output:
14           location: npm
15           token: ${NPM_TOKEN}
16           package-name: your-package-name # <--- add this field
17       - name: fernapi/fern-ruby-sdk
18         version: 1.12.1
19         output:
20           location: rubygems
21           token: ${RUBYGEMS_TOKEN}
22           package-name: your-package-name # <--- add this field
23       - name: fernapi/fern-csharp-sdk
24         version: 2.65.0
25         output:
26           location: nuget
27           api-key: ${NUGET_API_KEY}
28           package-name: your-package-name # <--- add this field
29         ...
30       - name: fernapi/fern-java-sdk
31         version: 4.8.0
32         output:
33           location: maven
34           coordinate: com.your-org:your-package-name # <--- add this field
35         ...
36       - name: fernapi/fern-php-sdk
37         version: 2.9.0
38         github:
39           repository: your-organization/your-repository
40         config:
41           packageName: YourPackageName # <--- add this field
42         ...
43       - name: fernapi/fern-go-sdk
44         version: 1.40.0
45         github:
46           repository: your-organization/your-repository # <--- add this field
47         ...

Add the package name to your docs configuration

Add the package name for the corresponding SDK to your docs.yml file:

For Python, TypeScript, Ruby, and .NET/C#, your-package-name must match the your-package-name that you configured in your generators.yml file.
For Java, com.your-org:your-package-name must match the coordinate that you configured in your generators.yml file.
For PHP, YourPackageName must match the packageName that you configured in your generators.yml file.
For Go, use the exact URL where the SDK repository is located, including the https://github.com/.

docs.yml

1 navigation:
2   - api: API Reference
3     snippets:
4       python: your-package-name  # <--- needs to match the naming in generators.yml
5       typescript: your-package-name # <--- needs to match the naming in generators.yml
6       ruby: your-package-name # <--- needs to match the naming in generators.yml
7       csharp: your-package-name # <--- needs to match the naming in generators.yml
8       java: com.your-org:your-package-name # <--- needs to match the coordinate in generators.yml
9       php: YourPackageName # <--- needs to match the packageName in generators.yml
10       go: https://github.com/your-organization/your-repository # <--- needs the https://github.com/ prefix

To display different package names for SDK users versus documentation users, use overrides files.

Trigger generation

Trigger your docs generation by running fern generate --docs locally or in CI/CD (i.e., GitHub Actions). The SDK snippets will appear via a dropdown!

Additional options

Specify SDK versions

You can specify which SDK version to use when generating code snippets.

docs.yml

1 navigation:
2   - api: API Reference
3     snippets:
4       python:
5         package: your-package-name  # <--- needs to match the naming in generators.yml
6         version: your-version number # SDK version to use for snippets

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

1 default-language: typescript
2 
3 navigation:
4   - api: API Reference
5     snippets:
6       python: your-package-name
7       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.

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.

Configuration

To configure SDK snippets, first name your SDKs in generators.yml and then reference that name in docs.yml.

Add examples to your API definition

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

Define a package name for your SDK(s)

Configure package names in your generators.yml file:

For Python, TypeScript, Ruby, and .NET/C#, add package-name: your-package-name to the output section.
For Java, add coordinate: com.your-org:your-package-name to the output section.
For PHP, add packageName: YourPackageName to the config section.
For Go, add repository: your-organization/your-repository to the github section.

Fern supports SDK snippets for TypeScript, Python, Ruby, Go, Java, PHP, and .NET/C#. File an issue to request additional languages.

generators.yml

1 groups:
2   production:
3     generators:
4       - name: fernapi/fern-python-sdk
5         version: 5.10.0
6         output:
7           location: pypi
8           token: ${PYPI_TOKEN}
9           package-name: your-package-name # <--- add this field
10         ...
11       - name: fernapi/fern-typescript-sdk
12         version: 3.69.0
13         output:
14           location: npm
15           token: ${NPM_TOKEN}
16           package-name: your-package-name # <--- add this field
17       - name: fernapi/fern-ruby-sdk
18         version: 1.12.1
19         output:
20           location: rubygems
21           token: ${RUBYGEMS_TOKEN}
22           package-name: your-package-name # <--- add this field
23       - name: fernapi/fern-csharp-sdk
24         version: 2.65.0
25         output:
26           location: nuget
27           api-key: ${NUGET_API_KEY}
28           package-name: your-package-name # <--- add this field
29         ...
30       - name: fernapi/fern-java-sdk
31         version: 4.8.0
32         output:
33           location: maven
34           coordinate: com.your-org:your-package-name # <--- add this field
35         ...
36       - name: fernapi/fern-php-sdk
37         version: 2.9.0
38         github:
39           repository: your-organization/your-repository
40         config:
41           packageName: YourPackageName # <--- add this field
42         ...
43       - name: fernapi/fern-go-sdk
44         version: 1.40.0
45         github:
46           repository: your-organization/your-repository # <--- add this field
47         ...

Add the package name to your docs configuration

Add the package name for the corresponding SDK to your docs.yml file:

For Python, TypeScript, Ruby, and .NET/C#, your-package-name must match the your-package-name that you configured in your generators.yml file.
For Java, com.your-org:your-package-name must match the coordinate that you configured in your generators.yml file.
For PHP, YourPackageName must match the packageName that you configured in your generators.yml file.
For Go, use the exact URL where the SDK repository is located, including the https://github.com/.

docs.yml

1 navigation:
2   - api: API Reference
3     snippets:
4       python: your-package-name  # <--- needs to match the naming in generators.yml
5       typescript: your-package-name # <--- needs to match the naming in generators.yml
6       ruby: your-package-name # <--- needs to match the naming in generators.yml
7       csharp: your-package-name # <--- needs to match the naming in generators.yml
8       java: com.your-org:your-package-name # <--- needs to match the coordinate in generators.yml
9       php: YourPackageName # <--- needs to match the packageName in generators.yml
10       go: https://github.com/your-organization/your-repository # <--- needs the https://github.com/ prefix

To display different package names for SDK users versus documentation users, use overrides files.

Trigger generation

Trigger your docs generation by running fern generate --docs locally or in CI/CD (i.e., GitHub Actions). The SDK snippets will appear via a dropdown!

Additional options

Specify SDK versions

You can specify which SDK version to use when generating code snippets.

docs.yml

1 navigation:
2   - api: API Reference
3     snippets:
4       python:
5         package: your-package-name  # <--- needs to match the naming in generators.yml
6         version: your-version number # SDK version to use for snippets

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

1 default-language: typescript
2 
3 navigation:
4   - api: API Reference
5     snippets:
6       python: your-package-name
7       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.

1	groups:
2	production:
3	generators:
4	- name: fernapi/fern-python-sdk
5	version: 5.10.0
6	output:
7	location: pypi
8	token: ${PYPI_TOKEN}
9	package-name: your-package-name # <--- add this field
10	...
11	- name: fernapi/fern-typescript-sdk
12	version: 3.69.0
13	output:
14	location: npm
15	token: ${NPM_TOKEN}
16	package-name: your-package-name # <--- add this field
17	- name: fernapi/fern-ruby-sdk
18	version: 1.12.1
19	output:
20	location: rubygems
21	token: ${RUBYGEMS_TOKEN}
22	package-name: your-package-name # <--- add this field
23	- name: fernapi/fern-csharp-sdk
24	version: 2.65.0
25	output:
26	location: nuget
27	api-key: ${NUGET_API_KEY}
28	package-name: your-package-name # <--- add this field
29	...
30	- name: fernapi/fern-java-sdk
31	version: 4.8.0
32	output:
33	location: maven
34	coordinate: com.your-org:your-package-name # <--- add this field
35	...
36	- name: fernapi/fern-php-sdk
37	version: 2.9.0
38	github:
39	repository: your-organization/your-repository
40	config:
41	packageName: YourPackageName # <--- add this field
42	...
43	- name: fernapi/fern-go-sdk
44	version: 1.40.0
45	github:
46	repository: your-organization/your-repository # <--- add this field
47	...

1	navigation:
2	- api: API Reference
3	snippets:
4	python: your-package-name # <--- needs to match the naming in generators.yml
5	typescript: your-package-name # <--- needs to match the naming in generators.yml
6	ruby: your-package-name # <--- needs to match the naming in generators.yml
7	csharp: your-package-name # <--- needs to match the naming in generators.yml
8	java: com.your-org:your-package-name # <--- needs to match the coordinate in generators.yml
9	php: YourPackageName # <--- needs to match the packageName in generators.yml
10	go: https://github.com/your-organization/your-repository # <--- needs the https://github.com/ prefix

1	default-language: typescript
2
3	navigation:
4	- api: API Reference
5	snippets:
6	python: your-package-name
7	typescript: your-package-name