使用受众筛选您的 API

了解如何使用 x-fern-audiences 为不同的 API 消费者（如公共用户和 beta 用户）筛选 OpenAPI 端点、模式和属性。

使用受众筛选您的 API

了解如何使用 x-fern-audiences 为不同的 API 消费者（如公共用户和 beta 用户）筛选 OpenAPI 端点、模式和属性。

团队版和企业版功能

此功能仅适用于团队版和企业版计划。要开始使用，请联系 support@buildwithfern.com。

Fern 提供两种方式来筛选哪些 API 元素会出现在您的 SDK 和 API 参考文档中：

audiences（基于标签的筛选）： 为特定端点、模式或属性标记受众标签，然后将 SDK 和文档筛选到这些标签。最适合基于用户类型（公共 vs beta、免费 vs 企业版）或功能成熟度创建变体，无论 URL 结构如何。
settings.filter（基于路径的筛选）： 筛选整个 URL 路径或模式。最适合您的 API 组织自然按 URL 划分的情况（如 /v1/* vs /v2/*，或 /admin/* vs /user/*）。配置详细信息请参见 settings.filter 参考。

许多团队同时使用这两种方法：基于路径的筛选用于主要划分，受众标签用于这些划分内的精细控制。

基于路径的筛选

在您的 generators.yml 中使用 settings.filter 来限制哪些端点会根据其路径包含在生成的 SDK 或 API 参考中：

generators.yml

1 api:
2   specs:
3     - openapi: "./openapi.yml"
4       settings:
5         filter:
6           endpoints: ["POST /users", "GET /users/{id}"]

基于标签的筛选（受众）

在您的 OpenAPI 规范中应用受众标签，然后配置您的 SDK 或 API 参考来筛选到这些受众。

在您的规范中标记元素

标记服务器

将 x-fern-server-name 和 x-fern-audiences 扩展添加到相关服务器。

在下面的示例中，Production 服务器仅对公共消费者可用：

openapi.yml

1 servers:
2   - url: https://api.com
3     x-fern-server-name: Production
4     x-fern-audiences:
5       - public

标记端点

将 x-fern-audiences 扩展添加到相关端点。

在下面的示例中，POST /users/sendEmail 端点仅对公共消费者可用：

openapi.yml

1 paths:
2   /users/sendEmail:
3     post:
4       x-fern-audiences:
5         - public
6       operationId: send_email

标记模式

将 x-fern-audiences 扩展添加到相关模式。

在此示例中，Email 类型对公共和 beta 客户都可用。

openapi.yml

1 components:
2   schemas:
3     Email:
4       title: Email
5       type: object
6       properties:
7         subject:
8           type: string
9         body:
10           type: string
11         to:
12           type: string
13       x-fern-audiences:
14         - public
15         - beta

标记属性

将 x-fern-audiences 扩展添加到相关属性。

在此示例中，to 属性仅对 beta 客户可用。

openapi.yml

1 components:
2   schemas:
3     Email:
4       title: Email
5       type: object
6       properties:
7         subject:
8           type: string
9         body:
10           type: string
11         to:
12           type: string
13           x-fern-audiences:
14             - beta

筛选 SDK 或文档

指定要包含在您的 SDK 或 API 参考文档中的受众。如果没有指定受众，所有标记的元素都将包含在您的 SDK 中，无论其受众标签如何。

SDK

文档

以下示例配置 SDK 筛选到 public 受众：

generators.yml

1 groups:
2   sdks:
3     audiences:
4       - public
5     generators:
6       - name: fernapi/fern-typescript-sdk
7         version: 0.8.8

团队版和企业版功能

此功能仅适用于团队版和企业版计划。要开始使用，请联系 support@buildwithfern.com。

Fern 提供两种方式来筛选哪些 API 元素会出现在您的 SDK 和 API 参考文档中：

audiences（基于标签的筛选）： 为特定端点、模式或属性标记受众标签，然后将 SDK 和文档筛选到这些标签。最适合基于用户类型（公共 vs beta、免费 vs 企业版）或功能成熟度创建变体，无论 URL 结构如何。
settings.filter（基于路径的筛选）： 筛选整个 URL 路径或模式。最适合您的 API 组织自然按 URL 划分的情况（如 /v1/* vs /v2/*，或 /admin/* vs /user/*）。配置详细信息请参见 settings.filter 参考。

许多团队同时使用这两种方法：基于路径的筛选用于主要划分，受众标签用于这些划分内的精细控制。

基于路径的筛选

在您的 generators.yml 中使用 settings.filter 来限制哪些端点会根据其路径包含在生成的 SDK 或 API 参考中：

generators.yml

1 api:
2   specs:
3     - openapi: "./openapi.yml"
4       settings:
5         filter:
6           endpoints: ["POST /users", "GET /users/{id}"]

基于标签的筛选（受众）

在您的 OpenAPI 规范中应用受众标签，然后配置您的 SDK 或 API 参考来筛选到这些受众。

在您的规范中标记元素

标记服务器

将 x-fern-server-name 和 x-fern-audiences 扩展添加到相关服务器。

在下面的示例中，Production 服务器仅对公共消费者可用：

openapi.yml

1 servers:
2   - url: https://api.com
3     x-fern-server-name: Production
4     x-fern-audiences:
5       - public

标记端点

将 x-fern-audiences 扩展添加到相关端点。

在下面的示例中，POST /users/sendEmail 端点仅对公共消费者可用：

openapi.yml

1 paths:
2   /users/sendEmail:
3     post:
4       x-fern-audiences:
5         - public
6       operationId: send_email

标记模式

将 x-fern-audiences 扩展添加到相关模式。

在此示例中，Email 类型对公共和 beta 客户都可用。

openapi.yml

1 components:
2   schemas:
3     Email:
4       title: Email
5       type: object
6       properties:
7         subject:
8           type: string
9         body:
10           type: string
11         to:
12           type: string
13       x-fern-audiences:
14         - public
15         - beta

标记属性

将 x-fern-audiences 扩展添加到相关属性。

在此示例中，to 属性仅对 beta 客户可用。

openapi.yml

1 components:
2   schemas:
3     Email:
4       title: Email
5       type: object
6       properties:
7         subject:
8           type: string
9         body:
10           type: string
11         to:
12           type: string
13           x-fern-audiences:
14             - beta

筛选 SDK 或文档

指定要包含在您的 SDK 或 API 参考文档中的受众。如果没有指定受众，所有标记的元素都将包含在您的 SDK 中，无论其受众标签如何。

SDK

文档

以下示例配置 SDK 筛选到 public 受众：

generators.yml

1 groups:
2   sdks:
3     audiences:
4       - public
5     generators:
6       - name: fernapi/fern-typescript-sdk
7         version: 0.8.8

1	api:
2	specs:
3	- openapi: "./openapi.yml"
4	settings:
5	filter:
6	endpoints: ["POST /users", "GET /users/{id}"]

1	servers:
2	- url: https://api.com
3	x-fern-server-name: Production
4	x-fern-audiences:
5	- public

1	paths:
2	/users/sendEmail:
3	post:
4	x-fern-audiences:
5	- public
6	operationId: send_email

1	components:
2	schemas:
3	Email:
4	title: Email
5	type: object
6	properties:
7	subject:
8	type: string
9	body:
10	type: string
11	to:
12	type: string
13	x-fern-audiences:
14	- public
15	- beta

1	groups:
2	sdks:
3	audiences:
4	- public
5	generators:
6	- name: fernapi/fern-typescript-sdk
7	version: 0.8.8