导入 OpenAPI 文件以更新现有 API 定义

您只能导入 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 定义并将它们合并到一起。对于小型增量变更，您可以使用资源更新操作。

要覆盖 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 置于相同的最终状态，如同第一次操作已成功一样。