OpenAPI扩展

服务器名称和 URL 模板化

以 Markdown 格式查看

Fern 支持多个扩展来配置 OpenAPI 规范中的 servers 块。使用 x-fern-server-name 为服务器提供可读的名称，然后将其与 URL 模板变量和 x-fern-default-url 结合使用，以在生成的 SDK 中支持动态基础 URL。

x-fern-server-name

使用 x-fern-server-name 为每个服务器条目提供可读的名称。Fern 在生成的环境枚举中使用此名称。

x-fern-server-name 扩展用于命名您的服务器。

openapi.yml
1servers:
2  - url: https://api.example.com
3    x-fern-server-name: Production
4  - url: https://sandbox.example.com
5    x-fern-server-name: Sandbox

在生成的 TypeScript SDK 中，您会看到：

environment.ts
1export const ExampleEnvironment = {
2  Production: "https://api.example.com",
3  Sandbox: "https://sandbox.example.com",
4} as const;
5
6export type ExampleEnvironment = typeof ExampleEnvironment.Production;

多个基础 URL

不同的端点可以针对不同的服务器。直接在端点上添加 servers 块以覆盖该路径的顶级服务器。使用 x-fern-server-name 为每个端点级服务器提供不同的名称，以便 Fern 能够正确分组。

openapi.yml
1paths:
2  /auth/token:
3    post:
4      servers:
5        - url: https://auth.example.com
6          x-fern-server-name: Auth

当 Fern 检测到多个命名服务器时，生成的 SDK 客户端会自动将每个端点解析到正确的基础 URL。

x-fern-server-name 也与 URL 模板变量一起使用，如下所示。

URL 模板化和 x-fern-default-url

URL 模板变量和 x-fern-default-url 目前仅支持 Python 和 Java SDK 生成。

对于跨多个区域、环境或自定义域部署的 API，您可以使用 {variable} 语法在服务器 url 中定义变量占位符。Fern 读取这些变量并将其作为生成的 SDK 中的可配置参数公开，以便用户可以在运行时自定义基础 URL。

由于像 https://api.{region}.example.com/v1 这样的模板化 URL 本身并不有效，因此使用 x-fern-default-url 提供具体的回退值。这样，不需要自定义变量的 SDK 用户就能获得开箱即用的工作客户端。

openapi.yml
1servers:
2  - url: https://api.{region}.{environment}.example.com/v1
3    description: Regional API server
4    x-fern-server-name: Default
5    x-fern-default-url: https://api.example.com/v1
6    variables:
7      region:
8        default: us-east-1
9        enum:
10          - us-east-1
11          - us-west-2
12          - eu-west-1
13      environment:
14        default: prod
15        enum:
16          - prod
17          - staging
18          - dev

每个变量都在 variables 映射下定义，并支持以下字段：

  • default — 当 SDK 用户未提供值时使用的回退值。此字段是 OpenAPI 规范所要求的。
  • enum — 允许值的可选列表。当提供时，Fern 在 SDK 中将变量生成为类型化枚举，而不是开放字符串。