使用受众筛选您的 API (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

api:
  specs:
    - openapi: "./openapi.yml"
      settings:
        filter:
          endpoints: ["POST /users", "GET /users/{id}"]

基于标签的筛选（受众）

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

在您的规范中标记元素

标记服务器

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

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

openapi.yml

servers:
  - url: https://api.com
    x-fern-server-name: Production
    x-fern-audiences:
      - public

标记端点

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

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

openapi.yml

paths:
  /users/sendEmail:
    post:
      x-fern-audiences:
        - public
      operationId: send_email

标记模式

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

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

openapi.yml

components:
  schemas:
    Email:
      title: Email
      type: object
      properties:
        subject:
          type: string
        body:
          type: string
        to:
          type: string
      x-fern-audiences:
        - public
        - beta

标记属性

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

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

openapi.yml

components:
  schemas:
    Email:
      title: Email
      type: object
      properties:
        subject:
          type: string
        body:
          type: string
        to:
          type: string
          x-fern-audiences:
            - beta

筛选 SDK 或文档

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

SDK

文档

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

generators.yml

groups:
  sdks:
    audiences:
      - public
    generators:
      - name: fern-typescript-sdk
        version: 0.8.8