> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI5ZDc0YjkwNS01NmVmLTQ1ZGYtYmZjYS0wMzUzNzI4MzM0MGYiLCJleHAiOjE3ODA2MDI0NjQsImlhdCI6MTc4MDYwMjE2NH0.Onp5g4j9PQiNYyr9Ac52VkhCsr0y_yLulcnIZAIg-Zk
>
> 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.

# 重写

> 使用单独的重写文件自定义您的 API 定义。

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

* 您的 API 规范是从服务器代码自动生成的
* 您需要为 SDK、文档或[生成的 CLI](/learn/cli-generator/get-started/customization#overrides-and-overlays) 使用不同的配置

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

对于 OpenAPI 规范，Fern 推荐使用[覆盖层](/learn/api-definitions/openapi/overlays)而不是重写。覆盖层遵循官方的 [OpenAPI Overlay 规范](https://spec.openapis.org/overlay/v1.0.0.html)，支持使用 JSONPath 通配符进行批量更改，并且在 OpenAPI 生态系统中是可移植的。

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

## 实现重写

在包含您的 API 定义的文件夹中[创建 `overrides.yml` 文件](/cli-api-reference/cli-reference/commands#fern-write-overrides)：

```bash {6}
fern/
  ├─ fern.config.json 
  ├─ generators.yml
  └─ spec-folder/
    ├─ spec-file.yml # API 定义
    └─ overrides.yml
```

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

对于 OpenAPI、AsyncAPI 和 OpenRPC，您可以使用 [Fern 的扩展](/learn/api-definitions/openapi/extensions/overview)来应用自定义。

```yml title="overrides.yml" {4-5}
paths: 
 /users: 
   post: 
    x-fern-sdk-group-name: users
    x-fern-sdk-method-name: create
```

```yaml title="generators.yml"
api:
  specs:
    - openapi: spec-file.yml 
      overrides: ./overrides.yml
```

您也可以指定[多个重写文件](#managing-overrides-across-apis)。

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

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

```yml title="overrides.yml" {4-5}
paths: 
 /users: 
   post: 
    x-fern-sdk-group-name: users
    x-fern-sdk-method-name: create
```

```yml title="combined" {4-5}
paths: 
 /users/post: 
  post: 
    x-fern-sdk-group-name: users
    x-fern-sdk-method-name: create      
    description: Create a User
    operationId: users_post
    requestBody: 
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'   
```

## 跨 API 管理重写

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

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

```yaml title="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 生成和文档使用完全不同的重写时，使用带有自己的 `generators.yml` 的单独文件夹。每个文件夹只引用与其关注点相关的重写：

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

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

```yaml title="sdks/generators.yml"
api:
  specs:
    - openapi: ../openapi.yml
      overrides:
        - ../shared-overrides.yml      # SDK 和文档的通用重写
        - sdk-overrides.yml            # SDK 特定的重写
```

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

```yaml title="generators.yml" {5, 12-13}
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 的添加。