适用于 Visual Studio Code 的 Azure API 中心扩展（预览版）入门

若要在 API 中心生成、发现、试用和使用 API，可以在 Visual Studio Code 开发环境中使用 Azure API 中心扩展：

• 生成 API - 在 API 中心注册 API，使生成的 API 可供其他人发现。 通过集成 Lint 分析支持，对 Visual Studio Code 进行 Shift-left API 设计一致性检查。 通过中断性变更检测确保新的 API 版本不会破坏 API 使用者的体验。

• 发现 API - 在 API 中心浏览 API，并查看其详细信息和文档。

• 试用 API - 使用 Swagger 用户界面或 REST 客户端浏览 API 请求和响应。

• 使用 API - 使用为 Microsoft Graph、GitHub 等平台生成 SDK 的 Microsoft Kiota 引擎，为您偏好的语言（包括 JavaScript、TypeScript、.NET、Python 和 Java）生成 API SDK 客户端。

先决条件

• Azure 订阅中的一个或多个 API 中心。 如果尚未创建 API 中心，请参阅快速入门：创建 API 中心。

  目前，你需要获配参与者角色或更高权限才能使用扩展访问 API 中心。

• Visual Studio Code

• 适用于 Visual Studio Code 的 Azure API 中心扩展

以下 Visual Studio Code 扩展为可选项，仅适用于所示的某些情况：

• REST 客户端扩展 - 直接发送 HTTP 请求并在 Visual Studio Code 中查看响应
• Microsoft Kiota 扩展 - 生成 API 客户端
• Spectral 扩展 - 用于在 Visual Studio Code 中运行左移 API 设计符合性检查
• Optic CLI - 用于检测 API 规范文档之间的中断性变更

安装

1. 通过 Visual Studio Code 市场安装适用于 Visual Studio Code 的 Azure API 中心扩展。 根据需要安装可选扩展。
2. 在 Visual Studio Code 的左侧“活动栏”中，选择“API 中心”。
3. 如果尚未登录 Azure 帐户，请选择“登录到 Azure...”，然后按照提示完成登录。 选择具备 API 中心访问权限的 Azure 帐户，该中心需包含你要查看的 API。 如果你有很多可供查看的订阅，你还可以筛选特定订阅。

注册 API

直接通过 Visual Studio Code 在 API 中心注册 API，方法是将其注册为一次性操作或使用 CI/CD 管道。

1. 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 输入 Azure API Center: Register API，然后按“Enter”。
2. 选择向 API 中心注册 API 的方式：
   • 分步操作最适合用于一次性 API 注册。
   • CI/CD 将预配置的 GitHub 或 Azure DevOps 管道添加到活动的 Visual Studio Code 工作区，该工作区在每次提交到源代码管理时作为 CI/CD 工作流的一部分运行。 建议使用 CI/CD 在 API 中心清点 API，以确保 API 元数据（包括规范和版本）在 API 中心保持最新状态，因为 API 会随着时间推移而不断发展。
3. 完成注册步骤：
   • 对于分步操作，选择要注册 API 的 API 中心，并根据提示回答 API 标题、类型、生命周期阶段、版本和规格等信息，完成 API 注册。
   • 对于 CI/CD，请选择 GitHub 或 Azure DevOps，具体取决于首选的源代码管理机制。 必须为 Azure API 中心扩展打开 Visual Studio Code 工作区，这样才能将管道添加到工作区。 添加文件后，完成 CI/CD 管道文件本身中记录的步骤以配置 Azure Pipeline/GitHub Action 环境变量和标识。 在推送到源代码管理时，系统会将 API 注册到 API 中心。

API 设计一致性

为了确保在生成 API 时设计符合组织标准，Visual Studio Code 的 Azure API 中心扩展为使用 Spectral 进行 API 规范检查提供了集成支持。

1. 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 输入“Azure API 中心：设置活动 API 样式指南”，然后按“Enter”。
2. 选择提供的默认规则之一，或者，如果你的组织已有样式指南，请使用“选择本地文件”或“输入远程 URL”，以在 Visual Studio Code 中指定活动规则集。 按“Enter”。

设置活动 API 样式指南后，打开任何基于 OpenAPI 或 AsyncAPI 的规范文件将在 Visual Studio Code 中触发本地 Lint 分析操作。 系统会在编辑器中以及“问题”窗口中以内联方式显示结果，（视图>问题或 Ctrl+Shift+M）。

中断性变更检测

引入新版 API 时，重要的是要确保引入的变更不会破坏旧版 API 上的 API 使用者的体验。 Visual Studio Code 的 Azure API 中心扩展可以对 Optic 所支持的 OpenAPI 规范文档进行中断性变更检测，使这一切变得简单。

1. 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 键入“Azure API 中心: 检测中断性变更”，然后按“Enter”。
2. 选择要比较的第一个 API 规范文档。 有效选项包括在 API 中心、本地文件或 Visual Studio Code 的活动编辑器中找到的 API 规范。
3. 选择要比较的第二个 API 规范文档。 有效选项包括在 API 中心、本地文件或 Visual Studio Code 的活动编辑器中找到的 API 规范。

Visual Studio Code 会打开两个 API 规范之间的差异视图。 系统会在编辑器中以及“问题”窗口中以内联方式显示任何中断性变更（“视图”>“问题”或 Ctrl+Shift+M）。

发现 API

API 中心资源显示在左侧的树状视图中。 展开 API 中心资源以查看 API、版本、定义、环境和部署。

使用“API”树视图项中显示的搜索图标在 API 中心内搜索 API。

查看 API 文档

可以在 API 中心查看有关 API 定义的文档，并尝试 API 操作。 此功能仅适用于 API 中心中基于 OpenAPI 的 API。

1. 展开 API 中心树状视图以显示 API 定义。

2. 右键单击定义，然后选择“打开 API 文档”。 此时会显示一个新选项卡，其中包含 API 定义的 Swagger 用户界面。

   

3. 若要试用 API，请选择终结点，选择“试用”，输入所需的参数，然后选择“执行”。

   注意

   根据所选 API，可能需要提供授权凭据或 API 密钥方可使用该 API。

生成 HTTP 文件

可以在 API 中心中根据 API 定义查看 .http 文件。 如果安装了 REST 客户端扩展，可以使用 Visual Studio Code 编辑器发出请求目录。 此功能仅适用于 API 中心中基于 OpenAPI 的 API。

1. 展开 API 中心树状视图以显示 API 定义。

2. 右键单击定义，然后选择“生成 HTTP 文件”。 此时会显示一个新选项卡，该选项卡会显示包含 API 规范的 .http 文档。

   

3. 若要发出请求，请选择一个终结点，然后选择“发送请求”。

   注意

   根据 API，可能需要提供授权凭据或 API 密钥才能发出请求。

生成 API 客户端

使用 Microsoft Kiota 扩展为你喜欢的语言生成 API 客户端。 此功能仅适用于 API 中心中基于 OpenAPI 的 API。

1. 展开 API 中心树状视图以显示 API 定义。
2. 右键单击定义，然后选择“生成 API 客户端”。 此时会显示 Kiota OpenAPI 生成器窗格。
3. 选择要包含在 SDK 中的 API 终结点和 HTTP 操作。
4. 选择“生成 API 密钥”。

   1. 输入有关 SDK 名称、命名空间和输出目录的配置详细信息。

   2. 为生成的 SDK 选择语言。

      

系统生成客户端。

有关使用 Kiota 扩展的详细信息，请参阅适用于 Visual Studio Code 的 Microsoft Kiota 扩展。

相关内容

• Azure API 中心 - 关键概念
• 使用适用于 Visual Studio Code 的 GitHub Copilot 聊天和 Azure API 中心扩展发现 API