Code exploration

显示 SDK 代码片段

以 Markdown 格式查看

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

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

动态代码片段

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

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

SDK 代码片段选择器

配置

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

1

向您的 API 定义添加示例

Fern 需要从您的 API 定义中读取请求示例来生成代码片段。对于 OpenAPI，请遵循 Swagger 的示例文档。

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 代码片段。提交 issue 以请求其他语言支持。
generators.yml
1groups:
2  production:
3    generators:
4      - name: fern-python-sdk
5        version: 5.14.21
6        output:
7          location: pypi
8          token: ${PYPI_TOKEN}
9          package-name: your-package-name # <--- 添加此字段
10        ...
11      - name: fern-typescript-sdk
12        version: 3.72.10
13        output:
14          location: npm
15          token: ${NPM_TOKEN}
16          package-name: your-package-name # <--- 添加此字段
17      - name: fern-ruby-sdk
18        version: 1.13.1
19        output:
20          location: rubygems
21          token: ${RUBYGEMS_TOKEN}
22          package-name: your-package-name # <--- 添加此字段
23      - name: fern-csharp-sdk
24        version: 2.68.12
25        output:
26          location: nuget
27          api-key: ${NUGET_API_KEY}
28          package-name: your-package-name # <--- 添加此字段
29        ...
30      - name: fern-java-sdk
31        version: 4.10.15
32        output:
33          location: maven
34          coordinate: com.your-org:your-package-name # <--- 添加此字段
35        ...
36      - name: fern-php-sdk
37        version: 2.10.14
38        github:
39          repository: your-organization/your-repository
40        config:
41          packageName: YourPackageName # <--- 添加此字段
42        ...
43      - name: fern-go-sdk
44        version: 1.46.0
45        github:
46          repository: your-organization/your-repository # <--- 添加此字段
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  # <--- 需要与 generators.yml 中的命名匹配
5      typescript: your-package-name # <--- 需要与 generators.yml 中的命名匹配
6      ruby: your-package-name # <--- 需要与 generators.yml 中的命名匹配
7      csharp: your-package-name # <--- 需要与 generators.yml 中的命名匹配
8      java: com.your-org:your-package-name # <--- 需要与 generators.yml 中的 coordinate 匹配
9      php: YourPackageName # <--- 需要与 generators.yml 中的 packageName 匹配
10      go: https://github.com/your-organization/your-repository # <--- 需要 https://github.com/ 前缀

要为 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  # <--- 需要与 generators.yml 中的命名匹配
6        version: your-version number # 用于代码片段的 SDK 版本

设置默认代码片段语言

在 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 端点请求和响应代码片段的信息？请查看我们关于端点请求代码片段和端点响应代码片段的文档。