设计和修改 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

请按照本页面上的说明使用 Cloud Code 设计和修改 API。

设计 API 时需要的其他角色

您需要具有下方所列角色才能执行本页面上所述的一些 API 设计和测试步骤。

任务	所需的角色
使用 Gemini Code Assist 设计 API	Gemini for Google Cloud User Service Usage Consumer 请参阅在 Google Cloud 项目中为 Gemini Code Assist 授予 IAM 角色。
设计 API 时使用 API Hub 中现有 API 的企业上下文	Cloud API Hub Viewer
将新的 API 注册到 API Hub	Cloud API Hub Editor 或 Admin
在 Cloud Code 中修改 API Hub API	Cloud API Hub Editor 或 Admin
设置和管理远程模拟服务器以测试 API	Artifact Registry Administrator Cloud Build Service Account Cloud Run Admin Service Usage Admin 请参阅 IAM 基本角色和预定义角色参考文档。

使用 Gemini Code Assist 设计 API

您可以使用 Cloud Code 通过 Gemini Code Assist 设计 OpenAPI 规范 (OAS) 3.0 版 API。Gemini Code Assist 可以在 API 开发过程中为生成式 AI 辅助添加企业上下文。企业上下文在生成新的 API 时使用项目的 API Hub API 作为上下文，并且仅适用于使用 API Hub 的项目。

如需了解在此部分中使用该功能的设置步骤，请参阅使用 Gemini Code Assist。

生成 API

要生成 API，请按以下步骤操作：

点击左侧导航栏中的魔杖，使用 Gemini Code Assist 创建新的 API 规范。请务必使用此方法创建 API 规范，而非使用 Gemini Code Assist 聊天，因为在创建 API 规范时，Gemini Code Assist 聊天不支持所有功能。
在 Create an API spec 输入窗口中输入描述新 API 的提示。
1. 如果需要，请从显示的模板条状标签中选择提示模板。提示模板会为您的提示提供一个框架，可帮助您入门。
2. 输入提示。请参阅如何撰写有效的 API 规范提示。
Gemini Code Assist 会生成一个定义 API 的 OAS。
审核规范：
1. 点击查看代码以在代码编辑器中查看规范。
2. API 渲染程序面板会预览开发者看到的 API，包括 API 说明和其他文档。
3. 如果您在 API Hub 中已有 API，则系统会使用企业上下文重复使用来自其他 API 的对象，添加到此 OAS 中，并在 OUTPUT 面板中枚举：
4. 感谢您的反馈！通过点击 Swagger 面板中的喜欢或不喜欢图标，提供有关生成的规范的反馈。
5. 如果您要修改预览版提示并重新生成规范，请点击提示上方的提示历史记录箭头以在之前的提示之间切换。
测试规范。新规范完成后，您可以使用模拟服务器对其进行测试。请参阅使用模拟服务器测试 API。
点击保存，使用您选择的名称保存新 API。
如需根据此规范创建 Apigee API 代理，请点击更多菜单中的 Create API proxy。此创建过程会创建一个代理软件包。新代理应该会显示在代理的左侧菜单列表中。如需详细了解如何通过 Cloud Code 创建代理，请参阅 Cloud Code 中集成的 API 代理创建演示。

如何撰写有效的 API 规范提示

生成的 API 规范的准确性和适用性在很大程度上取决于为模型提供的提示。

以下是高质量的提示的示例：

Create an API that allows customers to pay for an order using various payment methods such as credit cards and debit cards.
Accept purchase orders for specialized coffee bean purchases through an API.
We are a pizza company and want to create an online customized pizza delivery solution. Create an api to accept the pizza orders.
API for food delivery business. 客户可以在一个订单中订购披萨、汉堡或三明治的组合。每类食物都有自己的架构。披萨有配料和尺寸。汉堡有配料和夹心类型。Sandwiches have bread type, meat type, veggies, cheese, and custom instructions.

这些示例展示了效果不佳的提示。请尽量避免使用以下结构的提示：

Create an API for my store. 此提示包含的信息太少，无法让模型生成完整且准确的规范。
Create a new refund API that reuses the order object. 您无需在创建新 API 时指定 Gemini Code Assist 应重复使用的对象；Gemini Code Assist 会自动检测最适合重复使用的对象。

向 API Hub 注册 API

审核和确定 API 后，请通过向 API Hub 注册该 API，将其提供给开发者：

点击注册到 API Hub。
按照提示注册 API。如需了解如何向 API Hub 注册以及您需要提供的信息，请参阅注册 API。

通过 Cloud Code 更新 API Hub API

通过 Cloud Code 修改 API Hub 规范时，您可以保存 API Hub 规范的新版本。

如需将规范保存为新版本，请点击 Swagger 面板中的更多选项... 按钮，然后点击 Publish to API hub。提供新的 API 版本 ID。新版本应该会显示在 Cloud Code 的 API Hub 列表中该 API 对应的版本列表中。

使用设置文件控制 Gemini Code Assist 行为

本部分介绍了如何通过设置文件管理 Gemini Code Assist 是否可用以及如何使用。

停用或启用 Gemini Code Assist

在 Cloud Code 中设置 Apigee 后（请参阅在 Cloud Code 中设置 Apigee），您可以将以下行添加到设置文件中，以暂时停用所有 Gemini Code Assist 功能：

"cloudcode.apigee.gemini.enable": false

移除该行或将其设置为 true（默认值）可重新启用 Gemini Code Assist。

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

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

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

您可以执行以下操作：

在 Swagger 面板中查看企业上下文中包含的修改数（如果有）：
在输出面板中查看包含的修改：

如需为新规范生成停用企业上下文，请在 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 时适用。

修改 API

如需使用 Cloud Code 修改 API Hub 目录中的现有 API，请按照以下说明操作。您在 Cloud Code 中所做的更改可以保存回 API Hub。

以下说明面向未使用适用于 Apigee 的 Gemini Code Assist 插件的用户。如需了解在设计和修改 API 时 Gemini Code Assist 提供的其他功能，请参阅使用 Gemini Code Assist 设计 API。

如需修改 API 规范，请执行以下操作：

确保您在 Cloud Code 中选择的项目是包含您要修改的 API 的 API Hub 目录所在的项目。
在左侧导航栏中，展开 API Hub 树。
从列表中选择要修改的 API 和版本。
在修改面板中修改规范。您还可以在 Swagger 面板中查看 API 操作。
（可选）使用模拟服务器测试 API。
使用 Swagger 面板中的更多按钮，然后使用 Publish to API hub，将更改保存为新版本。在出现提示时确认或更新版本，并将更改保存回 API Hub。新版本应该会显示在 Cloud Code 的 API Hub 列表中该 API 对应的版本列表中。

使用模拟服务器测试 API

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

使用本地模拟服务器

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

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

在服务器下拉菜单中选择本地模拟服务器（开发服务器）。
打开路径，然后点击试试看。
填写所有请求参数，然后点击执行。
您还可以在提示符中使用 curl 提交请求。使用服务器下拉菜单中的服务器地址和端口。

使用远程模拟服务器

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

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

部署 Google Cloud 远程模拟服务器会创建一个新的 Cloud Run 服务。该服务会使用 Cloud Build 为模拟服务器构建容器映像，并将容器映像上传到 Google 项目中的 Cloud Artifact Registry；您需要负责创建后产生的任何费用和维护。您还需要负责不再需要该服务时将其删除。请参阅什么是 Cloud Run？、管理服务和 Artifact Registry 文档。

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

从更多菜单中选择 Deploy mock server (Google Cloud)。
如果 API 尚未在 API Hub 中注册，请在系统提示时进行注册。
指定远程模拟服务器的详细信息：项目 ID、服务器名称和区域，然后点击创建以创建远程模拟服务器。
重要提示：请勿创建多个同名的远程模拟服务器，即使界面目前不会阻止您这样做。
生成远程模拟服务器需要几分钟时间。您可以在 Google Cloud 输出面板中查看进度。
远程模拟服务器创建完成后，您将在 Swagger 面板服务器列表和输出面板中看到远程服务器网址。
如需使用模拟服务器，请打开路径，然后点击试试看。

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

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

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

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

请按照以下步骤管理已部署的远程模拟服务器：

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