OpenAPI扩展

使用受众筛选您的 API

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

以 Markdown 格式查看
团队版、专业版和企业版功能

此功能仅适用于团队版（文档）、专业版（SDK）和企业版计划。要开始使用，请联系 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
1api:
2  specs:
3    - openapi: "./openapi.yml"
4      settings:
5        filter:
6          endpoints: ["POST /users", "GET /users/{id}"]

基于标签的筛选（受众）

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

1

在您的规范中标记元素

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

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

openapi.yml
1servers:
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
1paths:
2  /users/sendEmail:
3    post:
4      x-fern-audiences:
5        - public
6      operationId: send_email

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

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

openapi.yml
1components:
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
1components:
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
2

筛选 SDK 或文档

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

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

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