# 导入 OpenAPI 文件以更新现有 API 定义
<a name="api-gateway-import-api-update"></a>

 您只能导入 API 定义来更新现有 API，无需更改其终端节点配置以及阶段或阶段变量，或者引用 API 密钥。

 导入到更新操作可以使用两种模式进行：合并和覆盖。

当一个 API (`A`) 合并到另一个 (`B`) 中时，如果两个 API 中没有互相冲突的定义，生成的 API 会保留 `A` 和 `B` 两者的定义。如果出现冲突，合并 API (`A`) 的方法定义会覆盖接受并入的 API (`B`) 的相应方法定义。例如，假设 `B` 声明了以下方法，用于返回 `200` 和 `206` 响应：

```
GET /a
POST /a
```

`A` 声明了以下方法，用于返回 `200` 和 `400` 响应：

```
GET /a
```

如果 `A` 并入 `B` 中，生成的 API 会生成以下方法：

```
GET /a
```

返回 `200` 和 `400` 响应，以及 

```
POST /a
```

返回 `200` 和 `206` 响应。

当您将外部 API 定义分解为多个较小的部分，并希望一次只应用其中一个部分的更改时，合并 API 非常有用。例如，如果多个团队负责一个 API 的不同部分并以不同的速度提供更改，则可能会出现此情况。在这种模式下，没有在导入的定义中明确定义的现有 API 中的项目会被忽略。

如果一个 API (`A`) 覆盖另一个 API (`B`)，生成的 API 将采纳覆盖方 API (`A`) 的定义。当外部 API 定义包含一个 API 的完整定义时，覆盖 API 非常有用。在这种模式下，没有在导入的定义中明确定义的现有 API 中的项目会被删除。

 要合并 API，请将一个 `PUT` 请求提交至 `https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=merge`。`restapi_id` 路径参数值指定了将要与提供的 API 定义合并的 API。

 以下代码段显示了一个 `PUT` 请求的示例，该请求将作为负载的 JSON 格式的 OpenAPI API 定义与 API Gateway 中已指定的 API 合并。

```
PUT /restapis/<restapi_id>?mode=merge
Host:apigateway.<region>.amazonaws.com
Content-Type: application/json
Content-Length: ...

An OpenAPI API definition in JSON
```

 合并更新操作需要提取两个完整的 API 定义并将它们合并到一起。对于小型增量变更，您可以使用[资源更新](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)操作。

 要覆盖 API，请将一个 `PUT` 请求提交至 `https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=overwrite`。`restapi_id` 路径参数指定了将要被提供的 API 定义覆盖的 API。

 以下代码段显示了一个覆盖请求的示例，该请求的负载为 JSON 格式 OpenAPI 定义：

```
PUT /restapis/<restapi_id>?mode=overwrite
Host:apigateway.<region>.amazonaws.com
Content-Type: application/json
Content-Length: ...

An OpenAPI API definition in JSON
```

 如果未指定 `mode` 查询参数，则系统会假定合并。

**注意**  
 `PUT` 操作是幂等操作，不是原子操作。这意味着如果在处理过程中出现系统错误，则 API 可能会以不良状态结束。但是，重复该操作会成功将 API 置于相同的最终状态，如同第一次操作已成功一样。