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

导入 OpenAPI 规范

适用于：所有 API 管理层级

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

在本文中，学习如何：

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

注意

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

必备条件

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

• Azure CLI

  • 在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息，请参阅 Azure Cloud Shell 中的 Bash 快速入门。

    

  • 如需在本地运行 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 cmdlet 连接到 Azure 帐户。
  • 如果选择使用 Azure Cloud Shell：
    • 有关详细信息，请参阅 Azure Cloud Shell 概述。

导入后端 API

在本例中，你将为开源还原 API 导入 OpenAPI 规范，但你可以替换你选择的 OpenAPI 规范。

门户

1. 在 Azure 门户，导航到 API 管理实例。

2. 在左侧菜单中，选择“API”>“+ 添加 API”。

3. 在“从定义创建”下，选择“OpenAPI”。

   

4. 输入 API 设置。 可以在创建过程中设置这些值，也可以稍后转到“设置”选项卡来配置这些值。在导入和发布第一个 API 教程中对这些设置进行了说明。

5. 选择“创建” 。

Azure CLI

以下示例使用 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 命令更新设置。

PowerShell

以下示例使用 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 规范编辑器，请执行以下操作：

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

根据 OpenAPI 规范架构进行验证

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

在门户中测试新的 API

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

1. 选择上一步中创建的 API。

2. 选择“测试”选项卡。

3. 选择操作。 该页将显示查询参数的字段和标头的字段。

   注意

   在测试控制台中，API 管理自动填充 Ocp-Apim-Subscription-Key 标头，并配置内置全访问订阅的订阅密钥。 此密钥允许访问 API 管理实例中的每个 API。 可选择性地通过选择 HTTP 请求旁的“眼睛”图标来显示 Ocp-Apim-Subscription-Key 标头。

4. 根据操作，输入查询参数值、标头值或请求正文。 选择“发送”。

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

   提示

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

若要调试 API，请参阅教程：使用请求跟踪调试 API。

追加其他 API

可以为不同服务公开的 API 撰写 API，包括：

• OpenAPI 规范
• SOAP API
• GraphQL API
• Azure 应用服务中托管的 Web 应用
• Azure 函数应用
• Azure 逻辑应用
• Azure Service Fabric

按照以下步骤将其他 API 追加到现有 API。

注意

导入另一个 API 时，操作将追加到当前 API 后面。

1. 在 Azure 门户中转到自己的 Azure API 管理实例。

   

2. 在概述页面上或左侧的菜单上选择“API” 。

   

3. 单击要将另一个 API 追加到的 API 旁边的“...”。

4. 从下拉菜单中选择“导入”。

   

5. 选择要从中导入 API 的服务。

   

相关主题

• API 导入限制
• 导入 OpenAPI 规范
• 导入 SOAP API
• 导入 SOAP API 并将其转换为 REST
• 导入应用服务 API
• 导入容器应用 API
• 导入 WebSocket API
• 导入 GraphQL API
• 导入 GraphQL 架构并设置字段解析程序
• 导入 Azure Function App
• 导入 Azure 逻辑应用
• 导入 Service Fabric 服务
• 导入 Azure OpenAI API
• 导入 OData API
• 导入 SAP OData 元数据
• 导入 gRPC API
• 编辑 API

后续步骤

• 创建和发布产品
• 转换和保护已发布的 API