Skip to content

import-api-from-oas.md

Latest commit

 

History

History
119 lines (81 loc) · 6.12 KB

import-api-from-oas.md

File metadata and controls

119 lines (81 loc) · 6.12 KB
title Import an OpenAPI specification to Azure API Management | Microsoft Docs
description Learn how to import an OpenAPI specification to an API Management instance using the Azure portal, Azure CLI, or Azure PowerShell. Then, test the API.
services api-management
author dlepow
ms.service azure-api-management
ms.topic how-to
ms.date 02/02/2026
ms.author danlep
ms.custom engagement-fy23, devx-track-azurepowershell, devx-track-azurecli

Import an OpenAPI specification

[!INCLUDE api-management-availability-all-tiers]

This article shows how to import an OpenAPI specification backend API to Azure API Management using various tools. The article also shows how to test the API in API Management. For information about OpenAPI version support, see API import restrictions and known issues.

In this article, you learn how to:

[!div class="checklist"]

  • Import an OpenAPI specification using the Azure portal, Azure CLI, or Azure PowerShell
  • Test the API in the Azure portal

Prerequisites

Import a backend API

For this example, you import the OpenAPI specification for the open source Petstore API. You can substitute an OpenAPI specification of your choice.

Portal

  1. In the Azure portal, navigate to your API Management instance.

  2. In the left menu, select APIs > + Add API.

  3. Under Create from definition, select OpenAPI.

    :::image type="content" source="media/import-api-from-oas/oas-api.png" alt-text="Screenshot of creating an API from an OpenAPI specification in the portal." border="false":::

  4. Enter API settings. You can set the values during creation or configure them later by going to the Settings tab. The settings are explained in the Import and publish your first API tutorial.

  5. Select Create.

Azure CLI

The following example uses the az apim api import command to import an OpenAPI specification from the specified URL to an API Management instance named apim-hello-world. To import using a path to a specification instead of a URL, use the --specification-path parameter.

# 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

After you import the API, you can update the settings by using the az apim api update command.

PowerShell

The following example uses the Import-AzApiManagementApi Azure PowerShell cmdlet to import an OpenAPI specification from the specified URL to an API Management instance named apim-hello-world. To import using a path to a specification instead of a URL, use the -SpecificationPath parameter.

# 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

After you import the API, you can update the settings by using the Set-AzApiManagementApi cmdlet.

View and edit OpenAPI specification

In the Azure portal, use the OpenAPI specification editor to view, validate, or edit the specification for the API that you imported.

To use the OpenAPI specification editor:

  1. In the Azure portal, navigate to your API Management instance.
  2. In the left menu, under APIs, select APIs > <your API> > All operations.
  3. On the Design tab, in Frontend, select OpenAPI Specification editor (pencil icon). You can open the specification in JSON or YAML format.
  4. Review or edit the specification as needed. Save your changes.

Validate against an OpenAPI specification schema

You can configure API Management validation policies to validate requests and responses or elements of them against the schema in an OpenAPI specification. For example, use the validate-content policy to validate the size or content of a request or response body.

[!INCLUDE api-management-test-api-portal]

[!INCLUDE api-management-append-apis.md]

[!INCLUDE api-management-define-api-topics.md]