修改网关以使用 OpenAPI 3.x

本页介绍了如何修改现有 API 网关，以使用 OpenAPI 3.x 规范作为其 API 配置。

准备工作

• 确认您已配置一个具有 OpenAPI 2.0 规范的现有 API Gateway 实例。
• 安装 gcloud CLI。如需了解详情，请参阅安装 Google Cloud CLI。

修改 API 配置以使用 OpenAPI 3.x

如需修改现有的 OpenAPI 2.0 API Gateway 配置以使用 OpenAPI 3.x，请完成以下步骤：

查找当前 API 配置

查找与网关关联的 API 配置。

1. 描述您的 API Gateway 实例：

   gcloud api-gateway gateways describe GATEWAY_ID --project=PROJECT_ID --location=GATEWAY_LOCATION
   

   替换以下内容：

   • GATEWAY_ID：网关的 ID。
   • PROJECT_ID：您的 Google Cloud 项目 ID。
   • GATEWAY_LOCATION：网关的位置。

   输出会显示 apiConfig 路径，例如：

   apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-gateway-config
   createTime: '2025-03-25T02:49:58.641650649Z'
   defaultHostname: my-gateway-a1b2c3d4.uc.gateway.dev
   displayName: My gateway
   name: projects/my-project/locations/us-west1/gateways/my-new-gateway
   state: ACTIVE
   updateTime: '2025-03-25T02:51:52.674308428Z'
   

获取 OpenAPI 文档

如需获取您确定的 API 配置的 OpenAPI 文档，请执行以下操作：

1. 描述 API 配置：

   gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID --project=PROJECT_ID --view=FULL
   

   替换以下内容：

   • CONFIG_ID：API 配置的 ID。
   • API_ID：您的 API 的 ID。
   • PROJECT_ID：您的 Google Cloud 项目 ID。

   输出会显示 openapiDocuments 部分，其中包含 OpenAPI 文档的 base64 编码内容：

   createTime: '2024-02-16T21:11:36.293169474Z'
   displayName: my-api-config
   gatewayServiceAccount: projects/-/serviceAccounts/[e-mail]
   name: projects/my-project-id/locations/global/apis/my-api/configs/my-gateway-config
   openapiDocuments:
   -   document:
       contents: IyBvc...
       path: apigateway-config.yaml
   serviceConfigId: my-api-config-0a1fjkfeb7t8z
   state: ACTIVE
   updateTime: '2024-02-16T21:13:45.626771120Z'
   

解码 OpenAPI 文档

如需对 base64 编码的 OpenAPI 文档内容进行解码，请执行以下操作：

1. 解码 contents 值：

   echo 'IyBvc...' | base64 -d
   

   将 IyBvc... 替换为上一步中的实际 contents 值。

   输出会显示您的 OpenAPI 2.0 文档，例如：

   swagger: '2.0'
   info:
     title: API_ID
     description: Sample API on API Gateway with a Google Cloud Functions backend
     version: 1.0.0
   

将 OpenAPI 文档转换为 OpenAPI 3.x

您可以使用工具将 OpenAPI 2.0 文档转换为 OpenAPI 3.x 文档。例如，Swagger 编辑器提供了一个转换实用程序。

在最初转换为 OpenAPI 3.x 后，手动对文档应用任何其他更改，以与 OpenAPI 3.x 保持一致，并确保与 API Gateway 扩展程序和功能兼容。如需详细了解 API Gateway 中支持的 OpenAPI 3.x 扩展程序，请参阅 API Gateway 中的 OpenAPI 3.x 扩展程序。

下表介绍了所需的更改：

功能	OpenAPI 2.0	OpenAPI 3.x	变更说明
API 密钥	securityDefinitions	securitySchemes	API 密钥使用开箱即用的 OpenAPI API 密钥支持。转换工具通常会自动处理此问题。无需进行任何手动更改。
JWT 身份验证	x-google-audiences 等	x-google-auth	在 OpenAPI 2.0 扩展程序中，您可以使用 securityDefinition 实例上的各个扩展程序来定义 OAuth 配置。转换工具会将安全方案实例转换为 #/components/securitySchemes 并保留扩展程序。手动修改这些扩展程序，使其成为 x-google-auth 的子项，并移除 x-google- 前缀。值保持不变。
配额	x-google-management，x-google-quota	x-google-api-management，x-google-quota	在 OpenAPI 2.0 扩展程序中，您可以在 x-google-management 中定义指标和配额，并使用 x-google-quota 将它们附加到方法。转换工具会保留这些扩展服务。手动将指标和配额配置从 x-google-management 移至 x-google-api-management。 将配置更改为使用 YAML 键，并移除 valueType、metricKind 和 unit。从 x-google-quota 的实例中移除 metricCosts。
后端	x-google-backend	x-google-api-management，x-google-backend	在 OpenAPI 2.0 扩展程序中，您可以在 x-google-backend 中定义后端，并且配置会在定义的位置应用。在 OpenAPI 3.x 扩展程序中，您可以在 x-google-api-management 中定义后端，然后通过 x-google-backend 应用它。转换工具会保留此扩展程序。手动将配置移至 x-google-api-management。修改 x-google-backend 的实例以引用该配置。
端点	x-google-endpoints	x-google-endpoint，servers	在 OpenAPI 2.0 扩展中，您可以在 x-google-endpoints 中定义端点配置。在 OpenAPI 3.x 扩展程序中，您可以使用 x-google-endpoint，但它是 servers 的扩展程序，而不是根扩展程序。转换工具会保留此扩展程序。手动将其移至 servers 并移除 name 字段。例如： # OpenAPI 2.0 x-google-endpoints: - name: "my-api.apigateway.my-project.cloud.goog" allowCors: True # OpenAPI 3.0.x servers: - url: https://my-api.apigateway.my-project.cloud.goog/ x-google-endpoint: allowCors: True
API 名称	x-google-api-name	x-google-api-management	在 OpenAPI 2.0 扩展程序中，您可以在 x-google-api-name 中定义 API 名称。在 OpenAPI 3.x 扩展程序中，您可以使用 x-google-api-management 中的 apiName 字段。 手动将此配置移至 x-google-api-management。
允许所有流量	x-google-allow	不支持	从 OpenAPI 文档中移除此内容。API Gateway 在 OpenAPI 3.x 中不支持此功能。

创建新的 API 配置

使用修改后的 OpenAPI 3.x 文档创建新的 API 配置。

1. 创建 API 配置：

   gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION
   

   替换以下内容：

   • NEW_CONFIG_ID：API 配置的新 ID。
   • API_ID：您的 API 的 ID。
   • PROJECT_ID：您的 Google Cloud 项目 ID。
   • NEW_API_DEFINITION：OpenAPI 3.x 规范文件的路径。

更新网关

更新网关实例，以引用修改后的 OpenAPI 3.x 文档中的新 API 配置。

1. 更新网关：

   gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION
   

   替换以下内容：

   • GATEWAY_ID：网关的 ID。
   • API_CONFIG：新 API 配置的完整资源路径，例如：projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
   • PROJECT_ID：您的 Google Cloud 项目 ID。
   • GATEWAY_LOCATION：网关的位置。

后续步骤

• 详细了解 API Gateway。
• 探索 OpenAPI 规范。