重写 | 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

paths: 
 /users: 
   post: 
    x-fern-sdk-group-name: users
    x-fern-sdk-method-name: create

在 generators.yml 中添加引用

generators.yml

api:
  specs:
    - openapi: spec-file.yml 
      overrides: ./overrides.yml

您也可以指定多个重写文件。

Fern 组合您的规范和重写

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

paths: 
 /users: 
   post: 
    description: Create a User
    operationId: users_post
    requestBody: 
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'

跨 API 管理重写

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

跨多个规范的共享重写

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

generators.yml

api:
  specs:
    - openapi: ./payments-api.yml
      overrides:
        - ./shared-overrides.yml       # 所有规范的通用重写
        - ./payments-overrides.yml     # 支付特定的重写
    - openapi: ./users-api.yml
      overrides:
        - ./shared-overrides.yml       # 相同的通用重写
        - ./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

api:
  specs:
    - openapi: ../openapi.yml
      overrides: sdk-overrides.yml

如果 SDK 和文档重写共享一个公共基础，您可以在每个文件夹中使用多个重写文件以避免重复：

sdks/generators.yml

api:
  specs:
    - openapi: ../openapi.yml
      overrides:
        - ../shared-overrides.yml      # SDK 和文档的通用重写
        - sdk-overrides.yml            # SDK 特定的重写

不同环境的重写

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

generators.yml

groups:
  public:
    specs:
      - openapi: openapi.yml
        overrides: public-overrides.yml
    generators:
      ...
  internal:
    specs:
      - openapi: openapi.yml
        overrides:
          - public-overrides.yml           # 基础：所有公共重写
          - internal-overrides.yml         # 附加：仅内部重写
    generators:
      ...

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