跳到导航
OpenAPI

叠加层

以 Markdown 格式查看

叠加层允许您在不修改原始文件的情况下自定义 OpenAPI 规范。这在以下情况下很有用：

  • 您的 API 规范是从服务器代码自动生成的
  • 您需要为 SDK、文档或生成的 CLI 配置不同的设置
  • 您想要添加 Fern 配置，如分页或 SDK 方法名称
  • 您想要使用 JSONPath 通配符对多个端点进行批量更改

叠加层遵循 OpenAPI 叠加层规范 并在 OpenAPI 生态系统中可移植。

Fern 推荐对 OpenAPI 规范使用叠加层而非覆盖。

覆盖 也完全受支持。如果覆盖对您的团队有效，则无需切换。您也可以同时使用两者（先应用覆盖，再应用叠加层）。

配置叠加层

要使用叠加层，请在规范文件所在的文件夹中创建 overlays 文件，并在 generators.yml 中引用它：

generators.yml
api:
  specs:
    - openapi: openapi.json
      overlays: overlays.yml

定义叠加层文件

叠加层中的每个操作使用 JSONPath 定位元素，并应用 update 或 remove 操作：

openapi-overlays.yml
overlay: 1.0.0 # 必需：叠加层规范版本
info:
  title: Customize Plant Store API # 必需：叠加层用途的人类可读描述
  version: 1.0.0 # 必需：用于跟踪此叠加层更改的版本标识符
actions: # 必需：要应用的有序更改列表
  - target: $.info # 选择要修改的元素的 JSONPath 表达式
    update: # 与目标元素合并的属性
      x-fern-sdk-group-name: plants
  - target: $.paths['/plants/{plantId}'].get.parameters[?(@.name == 'plantId')]
    update:
      x-fern-parameter-name: id

Fern 要求在 JSONPath 过滤器表达式周围使用括号。使用 [?(@.name == 'plantId')] 而不是 [?@.name == 'plantId']。

使用 update 来更改标准 OpenAPI 属性，如描述、摘要或其他字段：

openapi-overlays.yml
overlay: 1.0.0
info:
  title: Improve API documentation
  version: 1.0.0
actions:
  - target: $.paths['/plants'].get
    update:
      summary: List all available plants
      description: Returns a paginated list of plants in the store inventory.

使用 update 添加 Fern 扩展：

openapi-overlays.yml
overlay: 1.0.0
info:
  title: Add Fern SDK customizations
  version: 1.0.0
actions:
  # 添加 SDK 组和方法名称
  - target: $.paths['/plants'].get
    update:
      x-fern-sdk-group-name: plants
      x-fern-sdk-method-name: list
  - target: $.paths['/plants'].post
    update:
      x-fern-sdk-group-name: plants
      x-fern-sdk-method-name: create
  # 重命名参数
  - target: $.paths['/plants/{plantId}'].get.parameters[?(@.name == 'includeDetails')]
    update:
      x-fern-parameter-name: withDetails

使用 remove: true 从规范中删除元素：

openapi-overlays.yml
overlay: 1.0.0
info:
  title: Remove internal endpoints
  version: 1.0.0
actions:
  - target: $.paths['/internal/debug']
    description: Remove debug endpoint from public SDK
    remove: true

跨 API 管理叠加层

generators.yml 中的每个规范接受一个叠加层文件。您可以在多个规范中引用同一个文件，或为不同的配置使用单独的文件。

当多个规范需要相同的自定义时，将它们指向同一个叠加层文件以避免重复：

generators.yml
api:
  specs:
    - openapi: ./payments-api.yml
      overlays: shared-overlays.yml       # 两个规范使用相同的叠加层
    - openapi: ./users-api.yml
      overlays: shared-overlays.yml

如果每个规范需要独特的自定义，请为每个规范创建单独的叠加层文件：

generators.yml
api:
  specs:
    - openapi: ./payments-api.yml
      overlays: payments-overlays.yml
    - openapi: ./users-api.yml
      overlays: users-overlays.yml

通过创建各自包含 generators.yml 的单独文件夹，为 SDK 生成与文档使用不同的叠加层文件：

fern
fern.config.json
openapi.yml
docs
generators.yml
docs-overlays.yml
sdks
generators.yml
sdk-overlays.yml
sdks/generators.yml
api:
  specs:
    - openapi: ../openapi.yml
      overlays: sdk-overlays.yml

为生产环境与内部 API 配置不同的叠加层：

generators.yml
groups:
  production:
    specs:
      - openapi: openapi.yml
        overlays: production-overlays.yml
    generators:
      ...
  internal:
    specs:
      - openapi: openapi.yml
        overlays: internal-overlays.yml
    generators:
      ...