Import an OpenAPI specification

APPLIES TO: All API Management tiers

This article shows how to import an "OpenAPI specification" backend API residing at This backend API is provided by Microsoft and hosted on Azure. The article also shows how to test the APIM API.

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


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


Import a backend API

  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.

    Screenshot of creating an API from an OpenAPI specification in the portal.

  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.

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.


    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.


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


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.

    Go to Azure API Mgmt instance

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

    Select APIs

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

  4. Select Import from the drop-down menu.

    Select import

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

    Select service

Validate against an OpenAPI specification

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.

Next steps