导入 OpenAPI 规范

适用于：API 管理的所有层级

本文介绍如何使用各种工具将 OpenAPI 规范后端 API 导入到Azure API Management。本文还演示如何在API Management中测试 API。有关 OpenAPI 版本支持的信息，请参阅 API 导入限制和已知问题。

本文将教您如何：

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

必备条件

API Management实例。如果还没有该实例，请完成以下快速入门：创建Azure API Management实例。

Azure CLI

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

导入后端 API

在本示例中，您将导入开源 OpenAPI 规范用于开源 Petstore API。可以替换所选的 OpenAPI 规范。

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

以下示例使用 az apim apim api import 命令将 OpenAPI 规范从指定的 URL 导入到名为 apim-hello-world 的 API Management 实例。若要使用规范的路径而不是 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 Management 实例。若要使用规范的路径而不是 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 规范

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

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

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

根据 OpenAPI 规范架构进行验证

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

在门户中测试新的 API

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

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

注意

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

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

提示

默认情况下，测试控制台将请求发送到API Management的 CORS 代理，该代理将请求转发到API Management实例，然后将请求转发到后端。此代理使用公共 IP 地址 13.91.254.72，并且只能访问公共终结点。如果要直接从浏览器将请求发送到 API Management 服务，请选择 Bypass CORS 代理。如果您想使用测试控制台，而您的 API 管理网关是孤立网络的，或者不允许从 CORS 代理传入流量，请使用此选项。