> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI3NTkxNWJiMy02N2E5LTRjNjktYTA1Mi1hYTE3ZWExZWZiMDAiLCJleHAiOjE3ODE1MTE1NDUsImlhdCI6MTc4MTUxMTI0NX0.2OMS7QwiGQw3hKfoAyU4L-YP3YELdeOoGvvIXaqWC9w
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 叠加层

> 使用 OpenAPI 叠加层规范来自定义您的 OpenAPI 定义，而无需修改原始规范。

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

* 您的 API 规范是从服务器代码自动生成的
* 您需要为 SDK、文档或[生成的 CLI](/learn/cli-generator/get-started/customization#overrides-and-overlays) 配置不同的设置
* 您想要添加 Fern 配置，如分页或 SDK 方法名称
* 您想要使用 JSONPath 通配符对多个端点进行批量更改

叠加层遵循 [OpenAPI 叠加层规范](https://spec.openapis.org/overlay/v1.0.0.html) 并在 OpenAPI 生态系统中可移植。

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

[覆盖](/learn/api-definitions/openapi/overrides) 也完全受支持。如果覆盖对您的团队有效，则无需切换。您也可以同时使用两者（先应用覆盖，再应用叠加层）。

## 配置叠加层

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

```yaml title="generators.yml"
api:
  specs:
    - openapi: openapi.json
      overlays: overlays.yml
```

## 定义叠加层文件

叠加层中的每个操作使用 [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) 定位元素，并应用 `update` 或 `remove` 操作：

```yaml title="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 属性，如描述、摘要或其他字段：

```yaml title="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 扩展](/api-definitions/openapi/extensions/overview)：

```yaml title="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` 从规范中删除元素：

```yaml title="openapi-overlays.yml" {8}
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` 中的每个规范接受一个叠加层文件。您可以在多个规范中引用同一个文件，或为不同的配置使用单独的文件。

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

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

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

```yaml title="generators.yml"
api:
  specs:
    - openapi: ./payments-api.yml
      overlays: payments-overlays.yml
    - openapi: ./users-api.yml
      overlays: users-overlays.yml
```

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

```yaml title="sdks/generators.yml"
api:
  specs:
    - openapi: ../openapi.yml
      overlays: sdk-overlays.yml
```

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

```yaml title="generators.yml" {5, 11}
groups:
  production:
    specs:
      - openapi: openapi.yml
        overlays: production-overlays.yml
    generators:
      ...
  internal:
    specs:
      - openapi: openapi.yml
        overlays: internal-overlays.yml
    generators:
      ...
```