默认值

x-fern-default 扩展让你可以为路径、头部或查询参数指定客户端默认值，包括在 x-fern-global-headers 下定义的头部。当存在此扩展时，生成的 SDK 会使参数变为可选，并在调用方省略时自动发送默认值。x-fern-default 支持 string 和 boolean 值；其他类型（如数字）会被忽略。

这对于固定 API 版本头部或区域路径参数非常有用，同时仍允许调用方覆盖该值。x-fern-default 在所有 SDK 语言中都受支持。

Fern 使用 x-fern-default 而不是标准的 OpenAPI default 属性，因为它们具有不同的语义。schema 上的 OpenAPI default 描述了服务器在参数被省略时假设的值——它是一个文档提示，不影响客户端行为。x-fern-default 指示生成的 SDK 在调用方未提供值时在每个请求中主动发送该值，确保参数始终在网络上存在。

路径参数

在下面的示例中，当调用方未指定 region 时，SDK 发送 us-east-1。

openapi.yml

1 paths:
2   /regions/{region}/resources:
3     get:
4       operationId: list_resources
5       parameters:
6         - name: region
7           in: path
8           required: true
9           x-fern-default: "us-east-1"
10           schema:
11             type: string

头部

在下面的示例中，当调用方未指定 X-API-Version 时，SDK 发送 2024-02-08。

openapi.yml

1 paths:
2   /users:
3     get:
4       operationId: list_users
5       parameters:
6         - name: X-API-Version
7           in: header
8           x-fern-default: "2024-02-08"
9           schema:
10             type: string

查询参数

在下面的示例中，当调用方未指定 verbose 时，SDK 发送 false。

openapi.yml

1 paths:
2   /search:
3     get:
4       operationId: search
5       parameters:
6         - name: verbose
7           in: query
8           x-fern-default: false
9           schema:
10             type: boolean

全局头部

在下面的示例中，当调用方未指定 X-API-Version 全局头部时，SDK 发送 2024-02-08。

openapi.yml

1 x-fern-global-headers:
2   - header: X-API-Version
3     name: version
4     x-fern-default: "2024-02-08"

这对于固定 API 版本头部或区域路径参数非常有用，同时仍允许调用方覆盖该值。x-fern-default 在所有 SDK 语言中都受支持。

路径参数

在下面的示例中，当调用方未指定 region 时，SDK 发送 us-east-1。

openapi.yml

1 paths:
2   /regions/{region}/resources:
3     get:
4       operationId: list_resources
5       parameters:
6         - name: region
7           in: path
8           required: true
9           x-fern-default: "us-east-1"
10           schema:
11             type: string

头部

在下面的示例中，当调用方未指定 X-API-Version 时，SDK 发送 2024-02-08。

openapi.yml

1 paths:
2   /users:
3     get:
4       operationId: list_users
5       parameters:
6         - name: X-API-Version
7           in: header
8           x-fern-default: "2024-02-08"
9           schema:
10             type: string

查询参数

在下面的示例中，当调用方未指定 verbose 时，SDK 发送 false。

openapi.yml

1 paths:
2   /search:
3     get:
4       operationId: search
5       parameters:
6         - name: verbose
7           in: query
8           x-fern-default: false
9           schema:
10             type: boolean

全局头部

在下面的示例中，当调用方未指定 X-API-Version 全局头部时，SDK 发送 2024-02-08。

openapi.yml

1 x-fern-global-headers:
2   - header: X-API-Version
3     name: version
4     x-fern-default: "2024-02-08"

1	paths:
2	/regions/{region}/resources:
3	get:
4	operationId: list_resources
5	parameters:
6	- name: region
7	in: path
8	required: true
9	x-fern-default: "us-east-1"
10	schema:
11	type: string

1	paths:
2	/users:
3	get:
4	operationId: list_users
5	parameters:
6	- name: X-API-Version
7	in: header
8	x-fern-default: "2024-02-08"
9	schema:
10	type: string

1	paths:
2	/search:
3	get:
4	operationId: search
5	parameters:
6	- name: verbose
7	in: query
8	x-fern-default: false
9	schema:
10	type: boolean

1	x-fern-global-headers:
2	- header: X-API-Version
3	name: version
4	x-fern-default: "2024-02-08"