覆盖 | Fern Documentation

使用覆盖文件可以在不修改原始规范的情况下自定义您的 OpenAPI、AsyncAPI 或 OpenRPC 定义。这在以下情况下很有用：

您的 API 规范是从服务器代码自动生成的
您需要为 SDK 和文档配置不同的设置

覆盖功能适用于 OpenAPI、AsyncAPI 和 OpenRPC 规范。对于 Fern Definition 不需要覆盖，因为您可以直接编辑这些文件。

对于 OpenAPI 规范，Fern 建议使用叠加层而不是覆盖。叠加层遵循官方 OpenAPI 叠加层规范，支持使用 JSONPath 通配符进行批量更改，并且在 OpenAPI 生态系统中具有可移植性。

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

实现覆盖

创建覆盖文件

在包含您的 API 定义的文件夹中创建一个 overrides.yml 文件：

$ fern/
$   ├─ fern.config.json 
$   ├─ generators.yml
$   └─ spec-folder/
$     ├─ spec-file.yml # API 定义
$     └─ overrides.yml

覆盖文件的格式独立于规范。例如，即使您的 OpenAPI 规范是 JSON 格式，您也可以用 yaml 编写覆盖。

使用 Fern 扩展自定义您的规范

对于 OpenAPI、AsyncAPI 和 OpenRPC，您可以使用 Fern 的扩展来应用自定义。

overrides.yml

1 paths: 
2  /users: 
3    post: 
4     x-fern-sdk-group-name: users
5     x-fern-sdk-method-name: create

在 generators.yml 中添加引用

generators.yml

1 api:
2   specs:
3     - openapi: spec-file.yml 
4       overrides: ./overrides.yml

您也可以指定多个覆盖文件。

Fern 合并您的规范和覆盖

现在当您运行 fern generate 时，Fern 会将您的原始 API 规范与覆盖文件合并：

1 paths: 
2  /users: 
3    post: 
4     description: Create a User
5     operationId: users_post
6     requestBody: 
7       content:
8         application/json:
9           schema:
10             $ref: '#/components/schemas/User'

跨 API 管理覆盖

overrides 字段接受单个路径或路径列表。当提供多个路径时，覆盖会按顺序依次应用，后面的文件对于冲突键会优先于前面的文件。

多个规范间的共享覆盖

当您的项目有多个需要相同基础覆盖的规范时，使用共享基础文件并在其上分层应用特定规范的覆盖。这避免了在每个规范中重复常见的覆盖（例如，SDK 方法名称或身份验证扩展）：

generators.yml

1 api:
2   specs:
3     - openapi: ./payments-api.yml
4       overrides:
5         - ./shared-overrides.yml       # 所有规范的通用覆盖
6         - ./payments-overrides.yml     # 支付特定的覆盖
7     - openapi: ./users-api.yml
8       overrides:
9         - ./shared-overrides.yml       # 相同的通用覆盖
10         - ./users-overrides.yml        # 用户特定的覆盖

SDK 和文档的单独覆盖

当您需要为 SDK 生成和文档使用完全不同的覆盖时，使用带有各自 generators.yml 的单独文件夹。每个文件夹只引用与其关注点相关的覆盖：

fern

fern.config.json

openapi.yml

docs

generators.yml

docs-overrides.yml

sdks

generators.yml

sdk-overrides.yml

sdks/generators.yml

1 api:
2   specs:
3     - openapi: ../openapi.yml
4       overrides: sdk-overrides.yml

如果 SDK 和文档覆盖共享一个通用基础，您可以在每个文件夹内使用多个覆盖文件来避免重复：

sdks/generators.yml

1 api:
2   specs:
3     - openapi: ../openapi.yml
4       overrides:
5         - ../shared-overrides.yml      # SDK 和文档的通用覆盖
6         - sdk-overrides.yml            # SDK 特定的覆盖

不同环境的覆盖

当您的公共和内部 API 共享相同的规范但需要不同的覆盖时，使用多个覆盖文件在公共基础上分层添加内部特定的内容。这在内部 API 是公共 API 超集时特别有用：

generators.yml

1 groups:
2   public:
3     specs:
4       - openapi: openapi.yml
5         overrides: public-overrides.yml
6     generators:
7       ...
8   internal:
9     specs:
10       - openapi: openapi.yml
11         overrides:
12           - public-overrides.yml           # 基础：所有公共覆盖
13           - internal-overrides.yml         # 附加：仅内部覆盖
14     generators:
15       ...

这避免了在内部配置中重复公共覆盖。internal-overrides.yml 文件只需包含内部 API 特定的添加内容。