默认值 (OpenAPI) | Fern Documentation

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

paths:
  /regions/{region}/resources:
    get:
      operationId: list_resources
      parameters:
        - name: region
          in: path
          required: true
          x-fern-default: "us-east-1"
          schema:
            type: string

头部

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

openapi.yml

paths:
  /users:
    get:
      operationId: list_users
      parameters:
        - name: X-API-Version
          in: header
          x-fern-default: "2024-02-08"
          schema:
            type: string

查询参数

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

openapi.yml

paths:
  /search:
    get:
      operationId: search
      parameters:
        - name: verbose
          in: query
          x-fern-default: false
          schema:
            type: boolean

全局头部

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

openapi.yml

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