通过

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

教程：在 API 清单中注册 API

  • 项目

在本教程中，通过使用 Azure 门户注册 API 并分配元数据，在组织的 API 中心启动 API 清单。

有关 API、API 版本、定义和可在 Azure API 中心列出清单的其他实体的背景信息，请参阅关键概念。

本教程介绍如何使用门户来完成以下操作：

  • 注册一个或多个 API
  • 使用 API 定义添加 API 版本

先决条件

注册 API

在 API 中心注册（添加）API 时，API 注册包括：

  • 标题（名称）、类型和说明
  • 版本信息
  • 指向文档和联系人的可选链接
  • 所定义的内置元数据和自定义元数据

注册 API 后，可以向 API 添加版本和定义。

以下步骤注册了两个示例 API：Swagger Petstore API 和会议 API（请参阅先决条件）。 如果需要，可以注册自己的 API。

  1. 在门户中，导航到你的 API 中心。

  2. 在左侧菜单中“资产”下，选择“API”>“+ 注册 API”。

  3. 在“注册 API”页中，为 Swagger Petstore API 添加以下信息。 在页面底部，你将看到在上一教程中定义的自定义“业务线”和“面向公众”元数据。

    设置 值 说明
    API 标题 输入 Swagger Petstore API。 你为 API 选择的名称。
    标识 输入前面的标题后，Azure API 中心会生成此标识符，你可以替代该标识符。 API 的 Azure 资源名称。
    API 类型 从下拉列表中选择“REST”。 API 的类型。
    摘要 （可选）输入摘要。 API 的摘要说明。
    说明 （可选）输入说明。 API 的说明。
    Version
    版本标题 输入所选的版本标题，例如 v1。 你为 API 版本选择的名称。
    版本标识 输入前面的标题后，Azure API 中心会生成此标识符，你可以替代该标识符。 版本的 Azure 资源名称。
    版本生命周期 从下拉列表中进行选择，例如“测试”或“生产”。 API 版本的生命周期阶段。
    外部文档 （可选）将一个或多个链接添加到外部文档。 API 文档的名称、说明和 URL。
    许可证 （可选）添加许可证信息。 API 许可证的名称、URL 和 ID。
    联系人信息 （可选）为一个或多个联系人添加信息。 API 联系人的姓名、电子邮件和 URL。
    业务线 如果在上一教程中添加了此元数据，请从下拉列表中进行选择，例如“市场营销”。 自定义元数据，用于标识拥有 API 的业务部门。
    面向公众 如果添加了此元数据，请选中复选框。 自定义元数据，用于标识 API 是面向公众还是仅供内部使用。

    在门户中注册 API 的屏幕截图。

  4. 选择创建。 API 已注册。

  5. 重复上述三个步骤以注册另一个 API，例如会议 API。

提示

在门户中注册 API 时，可以选择任何预定义的 API 类型或输入所选的其他类型。

API 将显示在门户的“API”页上。 将大量 API 添加到 API 中心后，请使用此页面上的搜索框和筛选器查找所需的 API。

门户中“API”页的屏幕截图。

注册 API 后，可以查看或编辑 API 的属性。 在“API”页上，选择 API 以查看用于管理 API 注册的页面。

添加 API 版本

在整个生命周期中，API 可以有多个版本。 可以在 API 中心向现有 API 添加版本，并可选择使用一个或多个定义文件。

在此处，将向其中一个 API 添加版本：

  1. 在门户中，导航到你的 API 中心。

  2. 在左侧菜单中，选择“API”，然后选择一个 API，例如“Swagger Petstore”。

  3. 在“API”页的“详细信息”下，选择“版本”>“+ 添加版本”。

    在门户中添加 API 版本的屏幕截图。

  4. 在“添加 API 版本”页中：

    1. 输入或选择以下信息：

      设置 值 说明
      版本标题 输入所选的版本标题，例如 v2。 你为 API 版本选择的名称。
      版本标识 输入前面的标题后，Azure API 中心会生成此标识符，你可以替代该标识符。 版本的 Azure 资源名称。
      版本生命周期 从下拉列表中进行选择，例如“生产”。 API 版本的生命周期阶段。

    2. 选择创建。 已添加版本。

将定义添加到版本

通常需要将 API 定义添加到 API 版本。 Azure API 中心支持通用文本规范格式的定义，例如用于 REST API 的 OpenAPI 2 和 3。

若要向版本添加 API 定义，请：

  1. 在 API 的“版本”页上，选择 API 版本。

  2. 在 API 版本的左侧菜单中，在“详细信息”下选择“定义”>“+ 添加定义”。

  3. 在“添加定义”页中：

    1. 输入或选择以下信息：

      设置 值 说明
      标题 输入所选标题，例如“v2 定义”。 你为 API 定义选择的名称。
      标识 输入前面的标题后，Azure API 中心会生成此标识符，你可以替代该标识符。 定义的 Azure 资源名称。
      描述 （可选）输入说明。 API 定义的说明。
      规范名称 对于 Petstore API，请选择“OpenAPI”。 API 的规范格式。
      规范版本 输入所选的版本标识符，例如 3.0。 规范版本。
      Document 浏览到 Petstore API 的本地定义文件，或输入一个 URL。 示例 URL：https://raw.githubusercontent.com/swagger-api/swagger-petstore/refs/heads/master/src/main/resources/openapi.yaml API 定义文件。

      在门户中添加 API 定义的屏幕截图。

    2. 选择创建。 已添加定义。

本教程介绍如何使用门户来完成以下操作：

  • 注册一个或多个 API
  • 使用 API 定义添加 API 版本

生成 API 清单时，可利用自动化工具来注册 API，例如用于 Visual Studio Code 的 Azure API 中心扩展和 Azure CLI。

后续步骤

开始形成 API 清单了！ 现在可以添加有关 API 环境和部署的信息。

添加 API 环境和部署