重写 | Fern Documentation

使用重写文件来自定义您的 OpenAPI、AsyncAPI 或 OpenRPC 定义，而无需修改原始规范。这在以下情况下很有用：

您的 API 规范是从服务器代码自动生成的
您需要为 SDK、文档或生成的 CLI 使用不同的配置

重写功能适用于 OpenAPI、AsyncAPI 和 OpenRPC 规范。

对于 OpenAPI 规范，Fern 推荐使用覆盖层而不是重写。覆盖层遵循官方的 OpenAPI Overlay 规范，支持使用 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 的添加。