导入 OpenAPI 规范

2025-04-22

适用于：所有 API 管理层级

本文介绍如何使用各种工具将“OpenAPI 规范”后端 API 导入 Azure API 管理。本文还介绍如何在 API Management 中测试 API。

本文将教您如何：

使用 Azure 门户、Azure CLI 或 Azure PowerShell 导入 OpenAPI 规范
在 Azure 门户中测试 API

注意

API 导入限制和已知问题中记录了 API 导入限制。

必备条件

API 管理实例。如果你还没有 API 管理服务实例，请完成以下快速入门：创建 Azure API 管理实例。

Azure CLI

可以使用本地 Azure CLI。
- 如果需要，请安装 Azure CLI 来运行 CLI 参考命令。
- 本地 Azure CLI，请了解如何安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
  - 通过使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
  - 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
  - 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。
Azure PowerShell
- 如果选择在本地使用 Azure PowerShell：
  - 安装最新版本的 Az PowerShell 模块。
  - 使用 Connect-AzAccount -Environment AzureChinaCloud cmdlet 连接到 Azure 帐户。

导入后端 API

在 Azure 门户，导航到 API 管理实例。
在左侧菜单中，选择“API”“+ 添加 API”。
在“从定义创建”下，选择“OpenAPI”。
输入 API 设置。可以在创建过程中设置这些值，也可以稍后转到“设置”选项卡来配置这些值。在导入和发布第一个 API 教程中对这些设置进行了说明。
选择“创建” 。

以下示例使用 az apim api import 命令将 OpenAPI 规范从指定的 URL 导入到名为 apim-hello-world 的 API 管理实例。若要使用规范的路径而不是 URL 进行导入，请使用 --specification-path 参数。

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

导入 API 后，如果需要，可以使用 az apim api update 命令更新设置。

以下示例使用 Import-AzApiManagementApi Azure PowerShell cmdlet 将 OpenAPI 规范从指定的 URL 导入到名为 apim-hello-world 的 API 管理实例。若要使用规范的路径而不是 URL 进行导入，请使用 -SpecificationPath 参数。

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

导入 API 后，如果需要，可以使用 Set-AzApiManagementApi cmdlet 更新设置。

查看和编辑 OpenAPI 规范

在门户中，使用 OpenAPI 规范编辑器查看、验证或编辑你导入的 API 的规范。

若要使用 OpenAPI 规范编辑器，请执行以下操作：

在 Azure 门户，导航到 API 管理实例。
在左侧菜单中的“API”下，选择“API”><你的 API>>“所有操作”。
在“设计”选项卡的“前端”中，选择“OpenAPI 规范编辑器”（铅笔图标）。您可以以 JSON 或 YAML 格式打开规范。
根据需要审阅或编辑规范。保存所做更改。

根据 OpenAPI 规范架构进行验证

可以配置 API 管理验证策略，以根据 OpenAPI 规范中的架构验证请求和响应（或其元素）。例如，使用 validate-content 策略来验证请求或响应正文的大小或内容。

在门户中测试新的 API

可直接从管理门户调用操作，这为管理员查看和测试 API 的操作提供了一种方便的方式。

选择上一步中创建的 API。
选择“测试”选项卡。
选择操作。该页将显示查询参数的字段和标头的字段。

注意

在测试控制台中，API 管理自动填充 Ocp-Apim-Subscription-Key 标头，并配置内置全访问订阅的订阅密钥。此密钥允许访问 API 管理实例中的每个 API。可选择性地通过选择 HTTP 请求旁的“眼睛”图标来显示 Ocp-Apim-Subscription-Key 标头。
根据操作，输入查询参数值、标头值或请求正文。选择“发送”。

当测试成功时，后端会使用成功的 HTTP 响应代码和某些数据进行响应。

提示

默认情况下，测试控制台会将请求发送到 API 管理的 CORS 代理，该代理将请求转发到 API 管理实例，后者又将请求转发到后端。此代理使用公共 IP 地址 13.91.254.72，并且只能访问公共终结点。如果要将请求直接从浏览器发送到API 管理服务，请选择“绕过 CORS 代理”。如果要使用测试控制台，并且 API 管理网关与网络隔离或不允许来自 CORS 代理的流量，请使用此选项。