扩展

全局参数

以 Markdown 格式查看

全局参数是在 SDK 客户端级别或 CLI 配置级别设置一次，并注入到每个相关请求中的值，而不是在每次调用时传递。每次调用的值始终优先于全局值。

全局参数与全局请求头不同：全局请求头始终是 header，而全局参数可以目标为 header、query 参数、path 参数或请求体中的字段。

声明全局参数

在规范的根级别使用 x-fern-global-parameters 扩展。每个条目声明一个参数：

openapi.yml
1x-fern-global-parameters:
2  - name: currency
3    in: body
4    target: config.currency
5    env: ACME_CURRENCY
6    default: USD
7    optional: true
8    apply: auto
9    docs: The currency code used for pricing.
10  - name: region
11    in: path
12    target: regionId
13    env: ACME_REGION
14    default: us
15    apply: explicit

字段

name
stringRequired

参数的规范标识符。它是生成的标志或构造函数参数的基础，也是操作用来选择加入的键。

in
stringDefaults to body

值在线路上注入的位置：body、query、header 或 path。

target
string

线路级注入目标。对于 body，是请求体中的点分路径（例如 config.currency）。对于 query、header 和 path，是参数或头名称。默认为 name。

type
stringDefaults to string

值类型：string、integer、double 或 boolean。

env
string

当调用者未提供值时回退到的环境变量。

default
any

当调用者和环境变量都未提供值时使用的客户端默认值。x-fern-default 优先于 default。

optional
booleanDefaults to false

参数是否可以省略。没有值、默认值或环境变量的必需参数会产生错误。

apply
stringDefaults to explicit

参数如何应用于操作。explicit 仅应用于选择加入的操作；auto 应用于请求中包含目标的每个操作。

parameter-name
string

面向 SDK/CLI 的别名。设置后，此名称用于生成的标志或构造函数参数，而不是 name。

应用到特定操作

当参数使用 apply: explicit（默认值）时，它仅应用于通过每个操作的 x-fern-global-parameter 扩展选择加入的操作。列出要包含的参数名称。该值接受单个字符串或列表：

openapi.yml
1paths:
2  /v1/products/{regionId}/search:
3    post:
4      x-fern-global-parameter:
5        - region
6        - currency
7      operationId: searchProducts
8      # ...
9  /v1/products/{regionId}/{productId}:
10    get:
11      x-fern-global-parameter: region
12      operationId: getProduct
13      # ...

每个名称必须匹配 x-fern-global-parameters 中声明的参数。使用 apply: auto 的参数会注入到请求中包含其目标的每个操作中，无需选择加入。

解析顺序

在运行时，值按以下顺序从第一个可用来源解析：

  1. 每次调用的值（每个操作的参数或显式请求字段）——始终优先。
  2. CLI 标志或构造函数参数。
  3. 环境变量（env）。
  4. 客户端默认值（x-fern-default，然后是 default）。

对于带有嵌套 target 的 body 参数，调用者已在该路径提供的值永远不会被覆盖。

生成的 CLI 行为

CLI 生成器将每个全局参数注册为顶级标志（带有其 env 回退和 default），并将解析后的值注入到每个适用命令的声明位置。