Create Azure API management API with Bicep and swagger file

This document describes how to use Bicep templates to import an Azure API Management Backend API configurations using Open API specification a.k.a Swagger file.

Azure API Management (APIM) is used publish APIs to external, partner, and internal developers. APIM enables you to create and manage API gateways for existing backend services hosted anywhere. For more information, see the Overview.

Backend API in APIM is a HTTP service that implements your front-end API and its operations. When importing certain APIs, APIM configures the Backend API automatically. For example, APIM configures the backend when importing:

An OpenAPI specification.

A SOAP API.

Azure resources, such as an HTTP-triggered Azure Function App or Logic App.

Bicep is a domain-specific language (DSL) that uses declarative syntax to deploy and configure Azure resources.

Review the template - service.apis.bicep

This Bicep template imports and creates Backend API for existing Azure API management service. By default it expects that OAS spefication file comes in yaml format and uses OAS version 3.0.0 implementation.

param apimServiceName string = replace(resourceGroup().name, 'rg-', 'apim-')
// API name needs to unique in APIM
param name string = 'petstore'
@allowed([
  'yaml-v3' //uses 'openapi-link' format
  'json-v3' //uses 'openapi+json-link' format
])
param swaggerType string = 'yaml-v3'
// This url needs to be reachable for APIM
param urlToSwagger string = 'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml'
// There can be only one api without path
param apiPath string = ''
// param apiVersion string

// Existing APIM service
resource apimService 'Microsoft.ApiManagement/service@2021-01-01-preview' existing = {
  name: apimServiceName
}

var format = ((swaggerType == 'yaml-v3')  ? 'openapi-link' : 'openapi+json-link')

resource api 'Microsoft.ApiManagement/service/apis@2020-06-01-preview' = {
  name: '${apimService.name}/${name}'
  properties: {
    format: format
    value: urlToSwagger
    path: apiPath
    // apiVersion: apiVersion
    // apiVersionSetId: apiVersionSet.id
  }
}

//output nameWithVersion string = nameWithVersion
output name string = api.name
output id string = api.id

💡 TIP

Contents of Open API specification file can be validated with Swagger Editor.

Open API specification V2 support is limited to JSON file format only.

For OAS V2 use in Bicep properties.format property value 'swgger-link-json'.

The API import limitations are documented as known issues article.

Deploy the template to Azure

To deploy Bicep template to Azure, you need to sign-in to your Azure account using Azure command line interface (AZ CLI).

🚩 NOTE

Remember to sign in with your Azure AD account that has Contributor access role to your Azure API management environment.

Open a Visual Studio Code terminal window by selecting Terminal > New Terminal. The window usually opens at the bottom of the screen.}
Switch your terminal to the directory where you saved service.apis.bicep Bicep template.

In the Visual Studio Code terminal, sign in to Azure by running the following command:

az login

In the browser that opens, sign in to your Azure account.

The Visual Studio Code terminal displays a list of the subscriptions associated with this account.

Set the subscription context for all of the Azure CLI commands that you run in this session.

az account set --subscription "your-subscription-name"

Create resource group with Azure CLI

Create a new Azure resource group for your Azure development environment.

az group create --location westeurope --name "rg-yourgroup-we-dev"

Prerequisites for API import

You need existing Azure API Management service instance. Either complete MS docs quickstart Create an Azure API Management instance or follow instructions of my previous APIM post Create APIM service instance with Bicep.

Deploy service.apis.bicep template to Azure

Run the following command from the terminal in Visual Studio Code to deploy the Bicep template to Azure.

az deployment group create --template-file service.apis.bicep --resource-group "rg-yourgroup-we-dev" --name "apim-import-api-deploy"

Example above deploys template service.apis.bicep that creates a new Frontend API with name of petstore that maps to Backend API. Template uses example OAS V3 yaml file for Petstore API in GitHub as a default parameter.

Review deployed resources

Use the Azure portal to check the deployed resources or use Azure CLI to list the deployed APIM resources.

AZ-CLI

az apim api list --resource-group "rg-yourgroup-we-dev" --service-name "apim-yourgroup-we-dev"

Azure Portal

In the Azure portal, search for and select API Management services, and select the service instance you created.
Review petstore API under APIs > APIs page.