Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 21 additions & 19 deletions fern/products/docs/pages/api-references/sdk-snippets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,19 @@ title: Display SDK snippets
description: Enable SDK code examples in TypeScript, Python, Go, and more from the request and response examples documented in your API definition. Once enabled, Fern Docs will automatically populate the snippets within your API Reference.
---

If you use Fern's SDK Generator, you can automatically show SDK code snippets in your API Reference. SDK languages appear in a drop-down. By default, cURL snippets will be displayed to users.
When you use Fern's SDK Generator, you can automatically display SDK code snippets in your API Reference. These snippets appear in a language selector dropdown, with cURL as the default option.

<Note> Fern supports SDK snippets for TypeScript, Python, Ruby, Go, and .NET/C#. </Note>

<Frame>
![SDK code snippet selector](https://fern-image-hosting.s3.amazonaws.com/sdk-code-snippets.png)
</Frame>

## Configuring SDK Snippets

To configure SDK snippets, you'll need to name your SDKs in `generators.yml` and then reference that name in `docs.yml`. In the following example, we'll use `your-organization` as the package name because it is a common practice. For example, Stripe calls their npm package `stripe` and Twilio calls their PyPI package `twilio`.
To configure SDK snippets, you'll need to name your SDKs in `generators.yml` and then reference that name in `docs.yml`.

<Steps>

### Add examples to your API definition

Expand All @@ -20,7 +24,7 @@ In order to generate code snippets, Fern needs to read request examples from you
### Define a package name for your SDK(s)

Configure package names in your `generators.yml` file:
* For **Python/TypeScript/Ruby**, add `package-name: your-package-name` to the `output` section.
* For **Python, TypeScript, Ruby, and .NET/C#**, add `package-name: your-package-name` to the `output` section.
* For **Go**, add `repository: your-organization/your-repository` to the `github` section.

<CodeBlock title="generators.yml">
Expand All @@ -29,26 +33,32 @@ groups:
production:
generators:
- name: fernapi/fern-python-sdk
version: 2.8.0
version: <Markdown src="/snippets/version-number-python.mdx" />
output:
location: pypi
token: ${PYPI_TOKEN}
package-name: your-package-name # <--- add this field
...
- name: fernapi/fern-typescript-node-sdk
version: 0.20.9
version: <Markdown src="/snippets/version-number-ts.mdx" />
output:
location: npm
token: ${NPM_TOKEN}
package-name: your-package-name # <--- add this field
- name: fernapi/fern-ruby-sdk
version: 0.6.3
version: <Markdown src="/snippets/version-number-ruby.mdx" />
output:
location: rubygems
token: ${RUBYGEMS_TOKEN}
package-name: your-package-name # <--- add this field
- name: fernapi/fern-csharp-sdk
version: <Markdown src="/snippets/version-number-csharp.mdx" />
output:
location: nuget
api-key: ${NUGET_API_KEY}
package-name: your-package-name # <--- add this field
- name: fernapi/fern-go-sdk
version: 0.22.0
version: <Markdown src="/snippets/version-number-go.mdx" />
github:
repository: your-organization/your-repository # <--- add this field
...
Expand All @@ -62,7 +72,7 @@ groups:

### Add the package name to your docs configuration
Add the package name for the corresponding SDK to your `docs.yml` file:
* **For Python, TypeScript, and Ruby**, `your-package-name` must match the `your-package-name` that you configured in your `generators.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 Go**, use the exact URL where the SDK repository is located, including the `https://github.com/`.

<CodeBlock title="docs.yml">
Expand All @@ -73,6 +83,7 @@ navigation:
python: your-package-name # <--- needs to match the naming in generators.yml
typescript: your-package-name # <--- needs to match the naming in generators.yml
ruby: your-package-name # <--- needs to match the naming in generators.yml
csharp: your-package-name # <--- needs to match the naming in generators.yml
go: https://github.com/your-organization/your-repository # <--- needs the https://github.com/ prefix
```
</CodeBlock>
Expand All @@ -87,17 +98,6 @@ As the final step, trigger your docs generation by running `fern generate --docs

### Set default snippet language

SDK code snippets support several languages. Our development work is driven by customer requests, so please request support for languages not listed here by [opening an issue](https://github.com/fern-api/fern/issues/new/choose).

* csharp
* curl
* go
* java
* javascript
* python
* ruby
* typescript

To set the default snippet language, use the `default-language` key at the top indentation level of `docs.yml`.

<CodeBlock title="docs.yml">
Expand All @@ -112,6 +112,8 @@ navigation:
```
</CodeBlock>

</Steps>

## Access via API

If you'd like to bring SDK snippets into your own documentation, you can use the [Snippets API](/learn/api-reference/snippets/get). API access requires a [SDK Business plan](https://buildwithfern.com/pricing) or above.
Expand Down