API 发现和使用
API 的发现和使用是在整个组织中利用 API 的重要组成部分。
在本单元中,你将了解 API 中心 VS Code 扩展如何让你轻松发现和使用 API。
先决条件
若要通过 VS Code 上的 API 中心扩展管理 API,你需要:
- 安装 Visual Studio Code
- 安装 API 中心扩展
以下 Visual Studio Code 扩展为可选项,仅适用于所示的某些情况:
- REST 客户端扩展 - 用于发送 HTTP 请求并直接在 Visual Studio Code 中查看响应。
- Microsoft Kiota 扩展 - 用于生成 API 客户端。
API 发现和使用
可以使用你的所有 API、版本、定义、环境和部署,直接在 Visual Studio Code 中查看组织的 API 目录。 组织内可用的所有 API 一目了然。
但是,如果你的组织有数百或数千个 API,该怎么办? 别担心,可以通过搜索图标搜索 API,如下所示。
查看 API 文档
还可以在 VS Code 上快速访问、预览 API 文档和测试终结点。
- 从选项卡打开 API 中心扩展。
- 展开 API 中心树状视图以显示 API 定义。
- 右键单击定义并选择“打开 API 文档”。
- 此时会显示一个新选项卡,其中包含 API 定义的 Swagger 用户界面。
- 选择终结点并选择“试用”,提供所需的参数,然后选择“执行”。
试用 API
借助 API 中心扩展,可以根据 API 中心中提供的 API 定义查看 .http 文件。 在此文件中,可以直接在编辑器上发送 http 请求并查看响应。
注意
需要安装 REST 客户端扩展才能使用此功能。
- 展开 API 中心树状视图以显示 API 定义。
- 右键单击定义并选择“生成 HTTP 文件”。
- 此时会显示一个新选项卡,该选项卡会显示包含 API 规范的 .http 文档。
- 若要发出请求,请选择一个终结点,然后选择“发送请求”。
生成 SDK
API 中心扩展还能够使用 Microsoft Kiota 为你最喜欢的语言生成 HTTP REST API 的客户端,如 OpenAPI 规范中所定义。 这样就可以为你的 API 立即生成所有或所选终结点的客户端,以满足你的业务需求。
注意
需要安装 Microsoft Kiota 扩展才能使用此功能。
展开 API 中心树状视图以显示 API 定义。
右键单击定义并选择“生成 API 客户端”。 此时会显示 Kiota OpenAPI 生成器窗格。
选择要包含在 SDK 中的 API 终结点和 HTTP 操作。 可以将鼠标悬停在终结点上,然后选择“+”按钮添加它,或使用“-”移除它。
完成后,选择“运行”按钮生成 API 客户端。
选择“生成 API 密钥”。
a. 输入有关 SDK 名称、命名空间和输出目录的配置详细信息。
b. 为生成的 SDK 选择语言。
自承载 API 中心门户
API 中心门户是让开发人员和利益干系人可以无缝发现和使用 API 清单中的 API 的网站。 借助此自承载网站,组织为使用者提供了基于 Web 的 API 发现和使用体验。
API 平台工程师想要一个提供给其所有内外部 API 使用者的集中式独立位置。 若要开始,你可以使用 API 中心门户起始模板,步骤如下:
注意
下面的说明适用于部署到 Azure Static Web Apps,但你可以在自己选择的基础结构上部署。
分叉 API 中心引用实现代码。
在 Azure 上创建 Static Web App 资源。
在“部署详细信息”下,选择“GitHub”作为源,并指向包含 API 中心起始代码的存储库。
Static Web Apps 将检测生成预设,并使用 React 填充。
输入“/”作为“应用位置”。
输入“dist”作为输出位置。
选择创建。
最长可能需要 5 分钟才能看到在网站上发布的代码。
若要查看在 Static Web Apps 上运行的 API 中心门户,请从在 Azure 门户中创建的 Static Web App 资源的“概述”选项卡中,选择“在浏览器中查看应用”。
配置基于角色的访问控制
管理员可以通过基于角色的访问控制来完全控制权限分配,以访问组织的 API 中心内的 API 和资产。
注意
默认情况下,API 中心的管理员无权访问 API 中心门户中的 API。 请务必将 Azure API 中心数据读取者角色分配给自己和其他管理员。
若要访问 API 中心内的 API,用户必须登录到门户,并且必须具有限定于你的 API 中心的必要权限。 若要启用登录,请按照此处提供的步骤,将 Azure API 中心数据读者角色分配给你的组织中的用户或组。