修改 Cloud Endpoints 以使用 OpenAPI 3.x

本页介绍了在配置 Endpoints 时如何使用 OpenAPI 3.x 规范。

准备工作

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

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

完成以下步骤，将现有的 OpenAPI 2.0 Endpoints 配置修改为使用 OpenAPI 3.x。

查看部署历史记录

要查看部署历史记录，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往端点 > 服务页面。

    转到“Endpoints 服务”页面

  2. 从项目列表中，选择一个项目。

  3. 如果您有多个 API，请从列表中选择一个 API。

  4. 如需查看服务配置部署列表，请点击部署历史记录标签页。该列表显示以下内容：

    • 配置 ID。
    • 部署服务配置的日期。
    • 部署服务配置的人员。

查看服务配置

在部署历史记录标签页中，从列表中选择最近一次部署。界面上将显示已部署服务配置文件的内容。

将 OpenAPI 文档转换为 OpenAPI 3.x

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

在最初转换为 OpenAPI 3.x 后，手动对文档应用任何其他更改，以使其与 OpenAPI 3.x 保持一致，并确保与 Endpoints 扩展程序和功能兼容。

下表介绍了所需的更改：

功能 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.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 文档中移除此内容。Endpoints 在 OpenAPI 3.x 中不支持此功能。

重新部署服务配置

只要您更改了 OpenAPI 文档中的内容，就必须重新进行部署，以确保 Endpoints 采用最新版本的 API 服务配置。如果您之前部署了 ESP 且 rollout 选项设置为 managed，则无需重新部署或重启 ESP。此选项可将 ESP 配置为使用最新部署的服务配置。指定此选项后，在部署新的服务配置后，ESP 最多会在 5 分钟内检测到更改并自动开始使用该服务配置。建议您指定此选项，而非让 ESP 使用特定的配置 ID。

要部署 OpenAPI 文档，请执行以下操作：

  1. 将目录切换到 OpenAPI 文档所在的位置。

  2. 验证下面的命令返回的项目 ID，以确保不会在错误的项目中创建服务。

    gcloud config list project

    如果需要更改默认项目，请运行以下命令并将 YOUR_PROJECT_ID 替换为要在其中创建服务的 Google Cloud 项目 ID：

    gcloud config set project <var>YOUR_PROJECT_ID</var>

  3. 运行以下命令，并将 YOUR_OPENAPI_DOCUMENT 替换为描述 API 的 OpenAPI 文档名称：

    gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>

首次运行前面这条命令时，Service Management 会在默认项目中创建一项新的 Endpoints 服务，服务名称与您在 OpenAPI 文档的 host 字段中指定的文本一致。

在创建和配置服务时，Service Management 会向终端输出信息。成功完成后，您会看到如下所示的行，其中会显示服务配置 ID 和服务名称：

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

在前面的示例中，2017-02-13r0 是服务配置 ID，echo-api.endpoints.example-project-12345.cloud.goog 是服务名称。

成功部署后，您可以在 Google Cloud 控制台的 Endpoints > 服务页面上查看相应的 API。

如果您收到错误消息，请参阅排查 Endpoints 配置部署问题。

后续步骤