通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

通过适用于 Visual Studio Code 的 Azure API 中心扩展生成并注册 API

  • 项目

组织中的 API 生成者开发人员可以使用 Visual Studio Code 的 Azure API 中心扩展在 API 中心清单中生成和注册 API。 API 开发人员可以：

  • 通过一次性的操作将现有 API 添加到 API 中心，或者集成开发管道以将 API 注册为 CI/CD 工作流的一部分。
  • 使用 GitHub Copilot 从 API 代码生成新的 OpenAPI 规范。
  • 使用适用于 Azure 的 GitHub Copilot API 中心插件，通过自然语言提示创建新的 OpenAPI 规范。

API 生成者开发人员还可以利用扩展中的功能在 API 中心发现和使用 API，并确保实现 API 治理。

先决条件

指定的方案需要以下 Visual Studio Code 扩展：

安装

  1. 通过 Visual Studio Code 市场安装适用于 Visual Studio Code 的 Azure API 中心扩展。 根据需要安装其他扩展。

    注意

    值得注意的是，某些功能仅在 Azure API 中心扩展的预发布版本中可用。 从 Visual Studio Code Marketplace 安装扩展时，可以选择安装发布版本或预发布版本。 可以使用“扩展”视图中扩展的“管理”按钮上下文菜单随时在两个版本之间进行切换。

  2. 在 Visual Studio Code 的左侧“活动栏”中，选择“API 中心”。

    活动栏中的 API 中心扩展的屏幕截图。

  3. 如果尚未登录 Azure 帐户，请选择“登录到 Azure...”，然后按照提示完成登录。 选择一个 Azure 订阅，其中需包含你要用于查看 API 的 API 中心。 如果你有很多可供查看的订阅，你还可以筛选特定订阅。

注册 API - 分步说明

以下步骤通过一次性的操作在 API 中心注册 API。

  1. 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 输入 Azure API Center: Register API，然后按“Enter”。
  2. 选择“手动”。
  3. 选择要将 API 注册到的 API 中心。
  4. 回答提示中请求的信息，包括 API 标题、类型、版本标题、版本生命周期、定义标题、规范名称和定义文件，以完成 API 注册。

该 API 将添加到 API 中心清单中。

注册 API - CI/CD 管道

以下步骤使用 CI/CD 管道在 API 中心注册 API。 此选项会将预配置的 GitHub 或 Azure DevOps 管道添加到活动的 Visual Studio Code 工作区，该工作区在每次提交到源代码管理时作为 CI/CD 工作流的一部分运行。 建议使用 CI/CD 在 API 中心清点 API，以确保 API 元数据（包括规范和版本）在 API 中心保持最新状态，因为 API 会随着时间推移而不断发展。

  1. 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 输入 Azure API Center: Register API，然后按“Enter”。
  2. 选择 CI/CD。
  3. 选择“GitHub”或“Azure DevOps”，具体取决于首选的源代码管理机制。 必须为 Azure API 中心扩展打开 Visual Studio Code 工作区，这样才能将管道添加到工作区。 添加文件后，完成 CI/CD 管道文件本身中记录的步骤以配置所需的环境变量和标识。 在推送到源代码管理时，系统会将 API 注册到 API 中心。

详细了解如何设置 GitHub Actions 工作流以向 API 中心注册 API。

从 API 代码生成 OpenAPI 规范

使用 GitHub Copilot 的强大功能和适用于 Visual Studio Code 的 Azure API Center 扩展，从 API 代码创建 OpenAPI 规范文件。 右键单击 API 代码，从选项中选择“Copilot”，然后选择“生成 API 文档”。 GitHub Copilot 会创建 OpenAPI 规范文件。

注意

该功能在 API 中心扩展的预发布版本中可用。

演示如何使用 GitHub Copilot 从代码生成 OpenAPI 规范的动画。

生成 OpenAPI 规范文件并检查准确性后，可以使用“Azure API 中心: 注册 API”命令将该 API 注册到 API 中心。

使用自然语言提示生成 OpenAPI 规范

适用于 Azure 的 GitHub Copilot（预览版）的 API 中心插件可帮助你从自然语言提示开始设计新的 API。 借助 AI 帮助，快速生成符合组织标准的面向 API 开发的 OpenAPI 规范。

注意

该功能在 API 中心扩展的预发布版本中可用。

  1. 如果需要，请设置活动 API 样式指南。 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 键入“Azure API 中心：设置 API 样式指南”，进行选择，然后按“Enter”。

    如果未设置样式指南，则使用默认的 spectral:oas 规则集。

  2. 在聊天面板中，以自然语言的形式向 @azure 代理发出请求，以描述 API 的作用。 示例：

    @azure Generate OpenAPI spec: An API that allows customers to pay for an order using various payment methods such as cash, checks, credit cards, and debit cards.

    代理使用 OpenAPI 规范文档进行响应。

    显示如何使用 @azure 扩展从提示生成 OpenAPI 规范的屏幕截图。

  3. 查看生成的输出，了解 API 样式指南的准确性和符合性。 如有必要，可优化提示以重新生成。

    提示

    有效的提示侧重于 API 的业务要求，而不是实现详细信息。 较短的提示有时比较长的提示效果更好。

  4. 当它满足你的要求时，请将生成的 OpenAPI 规范保存到文件中。

  5. 将 API 注册到 API 中心。 在聊天面板中选择“在 API 中心注册 API”按钮，或从命令面板中选择“Azure API 中心：注册 API”，然后按照提示进行操作。

相关内容