Import an OpenAPI specification

APPLIES TO: All API Management 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.

In this article, you learn how to:

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

Note

API import limitations are documented in API import restrictions and known issues.

Prerequisites

• An API Management instance. If you don't already have one, complete the following quickstart: Create an Azure API Management instance.

• Azure CLI

  • Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

    

  • If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

• Azure PowerShell

  • If you choose to use Azure PowerShell locally:
    • Install the latest version of the Az PowerShell module.
    • Connect to your Azure account using the Connect-AzAccount cmdlet.
  • If you choose to use Azure Cloud Shell:
    • See Overview of Azure Cloud Shell for more information.

Import a backend API

For this example, you import the OpenAPI specification for the open source Petstore API, but 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.

   

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 importing the API, if needed, 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 importing the API, if needed, you can update the settings by using the Set-AzApiManagementApi cmdlet.

View and edit OpenAPI specification

In the 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.

Test the new API in the portal

Operations can be called directly from the portal, which provides a convenient way for administrators to view and test the operations of an API.

1. Select the API you created in the previous step.

2. Select the Test tab.

3. Select an operation. The page displays fields for query parameters and fields for the headers.

   Note

   In the test console, API Management automatically populates an Ocp-Apim-Subscription-Key header, and configures the subscription key of the built-in all-access subscription. This key enables access to every API in the API Management instance. Optionally display the Ocp-Apim-Subscription-Key header by selecting the "eye" icon next to the HTTP Request.

4. Depending on the operation, enter query parameter values, header values, or a request body. Select Send.

   When the test is successful, the backend responds with a successful HTTP response code and some data.

   Tip

   By default, the test console sends a request to API Management's CORS proxy, which forwards the request to the API Management instance, which then forwards it to the backend. This proxy uses public IP address 13.91.254.72 and can only reach public endpoints. If you want to send a request directly from the browser to the API Management service, select Bypass CORS proxy. Use this option when you want to use the test console and your API Management gateway is network-isolated or doesn't allow traffic from the CORS proxy.

To debug an API, see Tutorial: Debug your APIs using request tracing.

Append other APIs

You can compose an API of APIs exposed by different services, including:

• An OpenAPI specification
• A SOAP API
• A GraphQL API
• A Web App hosted in Azure App Service
• Azure Function App
• Azure Logic Apps
• Azure Service Fabric

Append a different API to your existing API using the following steps.

Note

When you import another API, the operations are appended to your current API.

1. Go to your Azure API Management instance in the Azure portal.

   

2. Select APIs on the Overview page or from the menu on the left.

   

3. Click ... next to the API that you want to append another API to.

4. Select Import from the drop-down menu.

   

5. Select a service from which to import an API.

   

Related topics

• API import limitations
• Import an OpenAPI specification
• Import a SOAP API
• Import a SOAP API and convert to REST
• Import an App Service API
• Import a Container App API
• Import a WebSocket API
• Import a GraphQL API
• Import a GraphQL schema and set up field resolvers
• Import an Azure Function App
• Import an Azure Logic App
• Import a Service Fabric service
• Import an Azure OpenAI API
• Import an OData API
• Import SAP OData metadata
• Import a gRPC API
• Edit an API

Next steps

• Create and publish a product
• Transform and protect a published API