OpenAPI扩展

全局请求头

以 Markdown 格式查看

有时，您的 API 会在每个端点或大部分端点中使用某些请求头，我们称之为”全局请求头”。为了方便起见，生成的 Fern SDK 提供了”全局请求头”功能，可以轻松地在 API 调用中更新它们。以 API 密钥为例，如果我们将 API 密钥声明为全局请求头，用户将能够轻松地插入他们的密钥：

1import os
2
3class Client:
4
5  def __init__(self, *, apiKey: str):

Fern 会自动提取在每个请求或大多数请求中使用的请求头，并将它们标记为全局的。

在您的 OpenAPI 规范中

要将其他请求头标记为全局的，或为全局请求头设置别名，请使用 x-fern-global-headers 扩展：

openapi.yml
1x-fern-global-headers:
2  - header: custom_api_key
3    name: api_key
4  - header: userpool_id
5    optional: true

当您使用 x-fern-global-headers 定义全局请求头时，您必须在 x-fern-examples 中包含它们。

默认值

使用 x-fern-default 为全局请求头设置客户端默认值。生成的 SDK 会将请求头设置为可选，并在调用者省略时发送默认值：

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

在 generators.yml 中

或者，您可以将请求头添加到generators.yml 文件中的 api 块：

generators.yml
1api:
2  - openapi: ./path/to/openapi
3    headers:
4      custom_api_key:
5        name: api_key
6        type: string
7      userpool_id:
8        name: userpool_id
9        type: optional<string>

生成的 SDK 行为

两种配置都会产生以下客户端代码：

1import os
2
3class Client:
4
5  def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str])