设计和修改 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面介绍了如何在 Cloud Code 的 Apigee 中设计和修改 API，并利用 Gemini Code Assist 加速 API 规范的创建、修改和管理。

准备工作

在使用本指南中的功能之前，请先满足以下条件：

确保您已完成在 Cloud Code for VS Code 中设置 Apigee API Management 的设置步骤，包括将 Gemini Code Assist 与 Apigee 搭配使用。
确保您的用户账号具有在 Apigee 中使用 Gemini Code Assist 所需的角色中列出的针对每个任务的所需角色。

撰写有效的 API 规范提示

在创建和修改 API 规范时，您需要在 Apigee 中提示 Gemini Code Assist。生成的 API 规范的准确性和适用性在很大程度上取决于提供给模型的提示。

如需撰写有效的 API 规范创建和修改提示，请遵循以下准则：

使用 Gemini Code Assist 对话时，请始终在提示的开头使用 Apigee 标识名 (@Apigee) 来创建或修改 API 规范。借助 Apigee 标识名，您可以访问 Apigee 工具，该工具包含本指南中所述的强大且功能丰富的 API 规范开发功能。
使用自然语言：在提示中使用措辞，就像是面对创建规范的人员。
具体说明：尽可能提供确切的要求，例如您的牙科诊所时间安排 API 需要包含多种预约类型和多个牙科诊所位置。
利用企业上下文而不指定对象名称：Gemini Code Assist 会智能地检测并重复使用 API Hub 目录中的现有架构、元数据和安全定义。虽然您无需指定确切的对象名称，但您可以通过在提示中添加 Use API Hub 或 Leverage Enterprise Context 等短语来提示此功能。
使用后续提示来迭代 API：您可以使用“Remove the locations entity from this API”等提示对 API 进行更改。

以下是创建和修改 API 规范时效果欠佳和效果更佳的提示示例：

提示效果欠佳	提示说明	提示效果更佳
"Create an API for my store."	此提示包含的信息太少，无法让模型生成完整且准确的规范。	"Create an API for my store for customers to check the availability of products and add items to their shopping cart." "Create an API that allows customers to pay for an order using various payment methods such as credit cards and debit cards."
"Create a new refund API that reuses the order object."	请勿在创建 API 时指定 Gemini Code Assist 应重复使用的对象；Gemini Code Assist 会自动检测最适合重复使用的对象。	"Create a new refund API that allows customers to request a refund for a previous order."
"Create an API for a delivery service."	生成的 API 过于宽泛。	"We are a pizza restaurant and want an online customized pizza delivery solution. Create an api to accept the pizza orders with pizza size and toppings." "API for food delivery business. 客户可以在一个订单中订购披萨、汉堡或三明治的组合。每类食物都有自己的架构。披萨有配料和尺寸。汉堡有配料和夹心类型。Sandwiches have bread type, meat type, veggies, cheese, and custom instructions."

使用 Gemini Code Assist 设计 API

您可以使用 Cloud Code 中的 Gemini Code Assist 设计 OpenAPI 规范 (OAS) 3.0 版 API。设计的 API 在生成新的 API 时可以包含企业上下文，并且仅适用于使用 API Hub 的项目。

如需了解在此部分中使用该功能的设置步骤，请参阅准备工作。

如需使用 Gemini Code Assist 生成新的 API，请按照以下步骤操作：

请使用以下方法之一来访问 API 规范创建提示：
- 从 Gemini Code Assist：对话：在对话窗口中，输入 Apigee 标识名 @Apigee，然后选择 Apigee 工具。
- 从 Cloud Code 中的 Apigee：点击 Apigee 所在行中的魔杖。这会加载 Gemini Code Assist：对话。使用 @Apigee 调用 Apigee 工具，开始创建规范。
从 Apigee 工具选项中选择创建 API 规范。
在提示中填写新 API 的说明。请参阅撰写有效的 API 规范提示。（请勿复制并粘贴 @Apigee 标识名。请改为在标识名后面输入或粘贴文本，以完成提示。)
提交提示。
Gemini Code Assist 会生成一个定义 API 的 OAS。（此过程最多可能需要 1 分钟。）如果 API Hub 包含其他 API，则新的 OAS 可能会整合目录中的对象和上下文。上下文对话摘要提供了有关所生成的 API 和所用来源的信息。
查看生成的规范。新 API 的 YAML 代码规范和 Swagger 面板会自动显示在标签页中。
新规范完成后，您可以使用模拟服务器对其进行测试。请参阅使用模拟服务器测试 API。
如需将新 API 保存到 API Hub 目录，请参阅将 API 发布到 API Hub。
如需根据此规范创建 Apigee API 代理软件包，请参阅将 API 保存为 API 代理软件包。

修改 API

您可以修改已在本地或 API Hub 目录中保存的 API。您在 Cloud Code 中所做的更改可以保存到 API Hub，也可以保存为 Apigee API 代理软件包。

从 API Hub 修改 API 规范

如需修改存储在 API Hub 目录中的 API 规范，请执行以下操作：

确保您在 Cloud Code 中选择的项目是包含您要修改的 API 的 API Hub 目录所在的项目。
在左侧导航栏中，展开 Apigee 部分中的 API Hub 树。
从列表中选择要修改的 API 和版本。
在 Swagger 面板中查看 API 操作。点击 Swagger 面板中的查看代码，以在修改标签页中打开 YAML 文件。

修改本地存储的 API 规范

如需修改本地存储的 API 规范，请在 Cloud Code 中打开 API 规范文件。您可以手动更新规范，也可以使用 Gemini Code Assist 对话迭代规范。

使用 Gemini Code Assist 对话迭代 API 规范

您可以使用 Gemini Code Assist 对话对现有的 API 规范进行更改：

按照来自 API Hub 的 API 规范或本地 API 规范文件中的说明，将规范文件加载到 Cloud Code 中。
确保包含规范的 YAML 文件是编辑器中当前处于活跃状态的标签页。
在 Gemini Code Assist 对话窗口中，输入 Apigee 标识名 @Apigee，然后选择 Apigee 工具。
输入规范更新提示。如需查看相关指导，请参阅撰写有效的 API 规范提示。
酌情使用模拟服务器测试 API。
如需将新 API 保存到 API Hub 目录，请参阅将 API 发布到 API Hub。
如需根据此规范创建 Apigee API 代理软件包，请参阅将 API 保存为 API 代理软件包。

将 API 发布到 API Hub

如果您使用的是 API Hub，则可以通过向 API Hub 注册 API 来将 API 提供给其他开发者：

在新的或修改后的 API 规范的 Swagger 面板中，点击发布到 API Hub。
在表单中，为 API 提供元数据，以提高 API 在 API Hub 目录中的可发现性和组织性。大多数字段都是从 API 规范自动填充的，但您可以更改这些值。如需了解如何向 API Hub 注册以及您需要提供的信息，请参阅注册 API。
- API 显示名称（必需）：API 的名称，对其他开发者可见。
- API 说明（可选）：API 的说明，供内部人员/开发者参考。
- API 所有者名称（可选）：API 所有者名称。
- API 所有者邮箱（可选）：所有者的邮箱。
- API 版本（必需）：API 版本。
- 生命周期阶段（可选）：从列表中选择一个阶段。
点击发布，将 API 发布到 API Hub。
短暂延迟后，您的更改应该会在 Cloud Code 的 Apigee 部分的 API Hub 树中可见。

使用模拟服务器测试 API

您可以使用本地模拟服务器或基于 Google Cloud的远程模拟服务器测试 API。本地模拟服务器已安装并默认可用，但您必须设置和管理 Google Cloud 模拟服务器。

使用本地模拟服务器

本地模拟服务器会接受对此 API 的请求并模拟响应。它只能供当前用户在当前会话期间使用。不过，与远程模拟服务器不同，本地模拟服务器无需进行设置或管理，也不会产生任何费用。

此外，本地模拟服务器还具有以下特点：

使用 Cloud Shell 编辑器或 Cloud Workstations 时不起作用。
使用 VS Code Remote Explorer 时可能无法正常运行。

如要使用本地模拟服务器，请执行以下操作：

在服务器下拉菜单中选择本地模拟服务器（如果尚未选择）：
在 Swagger 面板中打开路径，然后点击试试看。
填写所有请求参数，然后点击执行。

使用远程模拟服务器

远程模拟服务器可让您创建永久性模拟服务器实例，与本地模拟服务器不同，该实例可由组织中的其他人共享和使用，以便测试新 API。远程模拟服务器只能与在 API Hub 中注册的 API 配合使用。

远程模拟服务器不会自动更新您在部署模拟服务器后对 API 所做的任何更改，因此请等到您完全创建 API 后再添加模拟服务器。

部署 Google Cloud 远程模拟服务器会创建一项新的 Cloud Run 服务。该服务会使用 Cloud Build 为模拟服务器构建容器映像，并将容器映像上传到 Google 项目中的 Cloud Artifact Registry。请参阅什么是 Cloud Run？、管理服务以及 Artifact Registry 文档。

您可以使用默认服务账号，也可以提供受限更严格的服务账号来部署 Cloud Run 应用。如需了解详情，请参阅在 Cloud Code for VS Code 中管理 Cloud API 和 Cloud 客户端库。

如要部署远程模拟服务器，请执行以下操作：

从 Swagger 面板中选择部署模拟服务器。
如果 API 尚未在 API Hub 中注册，请在系统提示时进行注册。
指定远程模拟服务器的详细信息：服务器名称、安全服务器、服务账号（留空以使用默认服务账号），以及是否将服务器网址添加到 API 规范。点击创建以创建远程模拟服务器。
重要提示：请勿创建多个同名的远程模拟服务器，即使界面目前不会阻止您这样做。
生成远程模拟服务器需要几分钟时间。您可以在 Cloud Code 输出面板中查看进度，也可以通过 VS Code 右下角的通知弹出式窗口查看进度。
远程模拟服务器创建完成后，您将在 Swagger 面板服务器列表和输出面板中看到远程服务器网址。
如需使用模拟服务器，请打开路径，然后点击试试看。

填写所有请求参数，然后点击执行。

您还可以在提示中使用 curl 提交请求。使用服务器下拉菜单中的服务器地址和端口。

如要与其他用户共享对模拟服务器的访问权限，请执行以下操作：

向其他用户授予已部署服务的调用方角色。请参阅对开发者进行身份验证。
向模拟服务器发出请求时，用户应按照测试您的专用服务中的说明进行操作。

如需管理已部署的远程模拟服务器，请执行以下操作：

前往 Apigee API Hub。
找到相应 API，以查看该 API 的所有部署，其中包括任何远程模拟服务器。
使用资源网址前往部署，然后通过停止、删除模拟服务器并对模拟服务器执行其他操作来进行管理。

将 API 保存为 API 代理软件包

您可以将 API 保存为 Apigee API 代理软件包，以便在 Apigee 本地开发环境中对其进行处理。如需了解如何在 Cloud Code 中使用 API 代理，请参阅开发 API 代理。

点击 Swagger 面板中的创建 API 代理软件包。
在提示字段中，为 API 代理命名，然后继续。
API 代理会显示在本地工作区中的 Apigee 左侧菜单的 apiproxies 下。

在规范生成中控制企业上下文

OAS 生成可以包含您的组织的其他 API 中的架构、元数据和安全定义。该过程会使用对象名称和说明查找类似 API。系统不会考虑 API Hub API 的部署状态。

企业上下文默认处于启用状态。

如需为新规范生成停用企业上下文，请在 settings.json 文件中的 "cloudcode.apigee.gemini.enable": true 后面添加以下行：

"cloudcode.apigee.gemini.options": {
         "enterpriseContext": {
           "enabled": false,
           "includeMetadata": false,
           "includeSchema": false,
           "includeSecurity": false
         }
     }

其中：

enabled 用于指定企业上下文是否已全面启用。设置为 false 以停用企业上下文。
includeMetadata 可控制是否包含元数据上下文。此设置会包含或排除 API Hub 中其他 API 的元数据。includeMetadata 仅在 enabled 设置为 true 时适用。
includeSchema 可控制是否包含架构上下文。此设置会包含或排除 API Hub 中其他 API 的架构信息。includeSchema 仅在 enabled 设置为 true 时适用。
includeSecurity 用于控制是否包含安全相关上下文。此设置会包含或排除 API Hub 中其他 API 的安全信息。includeSecurity 仅在 enabled 设置为 true 时适用。