预览与发布Code exploration

显示 SDK 代码片段

以 Markdown 格式查看

如果您使用 Fern 来生成 SDK，可以在 API 参考中显示 SDK 代码片段。这些代码片段展示了如何在 TypeScript、Python、Go 和其他支持的语言中使用您的实际 SDK。

配置完成后，SDK 代码片段将替换 HTTP 代码片段。

动态代码片段

默认情况下，SDK 代码片段是动态代码示例，允许用户修改参数并实时查看所有支持语言的代码示例更新。

或者，您可以在 docs.yml 中禁用动态代码片段并使用静态代码示例。

SDK code snippet selector

配置

要配置 SDK 代码片段，首先在 generators.yml 中命名您的 SDK，然后在 docs.yml 中引用该名称。

1

向您的 API 定义添加示例

Fern 需要从您的 API 定义中读取请求示例来生成代码片段。

2

为您的 SDK 定义包名

在 generators.yml 文件中配置包名：

  • 对于 Python、TypeScript、Ruby 和 .NET/C#，在 output 部分添加 package-name: your-package-name。
  • 对于 Java，在 output 部分添加 coordinate: com.your-org:your-package-name。
  • 对于 PHP，在 config 部分添加 packageName: YourPackageName。
  • 对于 Go，在 github 部分添加 repository: your-organization/your-repository。
Fern 支持 TypeScript、Python、Ruby、Go、Java、PHP 和 .NET/C# 的 SDK 代码片段。提交问题以请求其他语言支持。
generators.yml
1groups:
2  production:
3    generators:
4      - name: fernapi/fern-python-sdk
5        version: 5.9.1
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.11.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.7.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.8.1
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.39.2
45        github:
46          repository: your-organization/your-repository # <--- add this field
47        ...
3

将包名添加到您的文档配置中

将相应 SDK 的包名添加到您的 docs.yml 文件中：

  • 对于 Python、TypeScript、Ruby 和 .NET/C#，your-package-name 必须与您在 generators.yml 文件中配置的 your-package-name 匹配。
  • 对于 Java，com.your-org:your-package-name 必须与您在 generators.yml 文件中配置的 coordinate 匹配。
  • 对于 PHP，YourPackageName 必须与您在 generators.yml 文件中配置的 packageName 匹配。
  • 对于 Go，使用 SDK 仓库所在的确切 URL，包括 https://github.com/。
docs.yml
1navigation:
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

要为 SDK 用户和文档用户显示不同的包名，请使用覆盖文件。

4

触发生成

通过在本地或 CI/CD（如 GitHub Actions）中运行 fern generate --docs 来触发文档生成。SDK 代码片段将通过下拉菜单出现！

其他选项

指定 SDK 版本

您可以指定生成代码片段时要使用的 SDK 版本。

docs.yml
1navigation:
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

设置默认代码片段语言

在 docs.yml 的顶级缩进使用 default-language 键。此设置适用于 SDK 代码片段和 HTTP 代码片段。

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

端点请求和响应代码片段

正在寻找有关生成 API 端点请求和响应代码片段的信息？请查看我们关于端点请求代码片段和端点响应代码片段的文档。