| title | description | services | author | ms.service | ms.topic | ms.date | ms.author | ms.custom |
|---|---|---|---|---|---|---|---|---|
Import an OpenAPI specification to Azure API Management | Microsoft Docs | 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 in the Azure portal. | api-management | dlepow | azure-api-management | how-to | 11/27/2024 | danlep | engagement-fy23, devx-track-azurepowershell, devx-track-azurecli |
[!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.
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
Note
API import limitations are documented in API import restrictions and known issues.
An API Management instance. If you don't already have one, complete the following quickstart: Create an Azure API Management instance.
Azure CLI [!INCLUDE azure-cli-prepare-your-environment-no-header.md]
Azure PowerShell [!INCLUDE azure-powershell-requirements-no-header]
For this example, you import the OpenAPI specification for the open source Petstore API, but you can substitute an OpenAPI specification of your choice.
In the Azure portal, navigate to your API Management instance.
In the left menu, select APIs > + Add API.
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":::
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.
Select Create.
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.
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.
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:
- In the Azure portal, navigate to your API Management instance.
- In the left menu, under APIs, select APIs > <your API> > All operations.
- On the Design tab, in Frontend, select OpenAPI Specification editor (pencil icon). You can open the specification in JSON or YAML format.
- Review or edit the specification as needed. Save your changes.
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]
