Azure API Management Integration

Microsoft Azure API Management allows developers to publish and maintain APIs in the Azure cloud. SwaggerHub integrates with Azure API Management, which allows you to easily export your API definitions to Azure. This way you can design your APIs on SwaggerHub, then deploy your API design to your Azure API Management instance from SwaggerHub, keeping the APIs updated with any changes you make to the design.

The vendor extension x-azure-api-id will be automatically added to your API definition to link it with the API saved to your Azure API Management service instance.

Important

SwaggerHub SaaS users who configured this integration for OpenAPI 2.0 definitions before July 9, 2019 need to re-authenticate the integration by clicking Sign in with Microsoft in the integration settings. The new authentication method uses dynamically issued access tokens, unlike the old tokens that had to be generated manually and were valid for 30 days only. SwaggerHub On-Premise users need to upgrade to v. 1.21.0 or later to make use of the new authentication method.

Video tutorial

 

Requirements

To use the integration, you need an active Microsoft Azure subscription. You can sign up at https://azure.microsoft.com. An Azure subscription is also included in the Visual Studio subscription and some other Microsoft subscriptions.

Note

This integration works only with the global Azure cloud (portal.azure.com), it does not support Azure Government Cloud (portal.azure.us).

Supported OpenAPI versions

This integration supports OpenAPI 2.0 and OpenAPI 3.0. SwaggerHub On-Premise users need v. 1.20.0 or later to use OpenAPI 3.0 definitions with Azure API Management.

Note

Azure API Management does not support some features of the OpenAPI Specification, specifically, recursive schemas. API definitions that use unsupported features cannot be imported to Azure.

Considerations

  • The integration is one-way, which means your API definitions go only from SwaggerHub to Azure API Management. You should edit your API definitions in SwaggerHub only.

  • The integration is bound to a specific version of the API and is not copied when you add a new version. To integrate different API versions with Azure, you need to add the integration to each version separately.

1. Create an Azure API management service instance

To use the integration, you must have an API Management service instance running in the Azure cloud. If you do not have one yet, follow the instructions in Create an API Management service instance.

API Management service instance in Azure

Click the image to enlarge it.

2. Additional steps for SwaggerHub On-Premise

SwaggerHub On-Premise requires some additional configuration in Azure and in the Admin Center before the users can use this integration. If you have already done this, proceed to the next step.

2a. Register an application in Azure

Applies to SwaggerHub On-Premise 1.20.0 and later.

To push API definitions from SwaggerHub On-Premise to Azure, you need to register an application in Azure AD that will be used to authorize the connection to Azure. The application’s client ID and secret need to be specified in the SwaggerHub On-Premise Admin Center. For instructions, see Configuring Azure API Management Integration.

2b. Generate an Azure access token

Applies to OpenAPI 2.0 definitions in SwaggerHub On-Premise versions before 1.21.0.

Important

These access tokens are valid for 30 days only. Before the token expires, you will have to generate a new one and update the token in SwaggerHub's integration settings. To avoid having to update the tokens, upgrade to the latest version of SwaggerHub On-Premise, which uses another method to authorize the integration.

To generate an access token:

  1. Open the Azure portal, https://portal.azure.com.

  2. On the left, select All resources.

  3. Click your service instance in the list.

    API Management service instance

  4. On the left, select Management API.

  5. Select the Enable API Management REST API check box.

  6. At the bottom, under Access token, click Generate.

    Generating an access token for Azure API Management

    Click the image to enlarge it.

  7. Copy the generated token (the entire string), because you will not be able to see it later.

    Copying the access token

3. Configure the integration

  1. Open your API in the SwaggerHub editor.

  2. If the API has several versions, select the version you want to push to Azure API Management.

    Selecting an API version

  3. If this version is publishedPublishing an API, unpublish it. Only unpublished APIs can be integrated with Azure API Management.

  4. Click the API name, switch to the Integrations tab, and click Add New Integrations:

    Add New Integration menu command

  5. Select Azure API Management from the list of integrations.

  6. Enter the integration parameters:

    • Name – Required. The display name for the integration.

    • Azure API Management service instance name – Required. The name of your Azure API Management service instance as it appears in the resources list in the Azure portal.

      Azure API Management service instance name

      The service instance name can also be found in the developer portal URL. It is the {name} part of the URL - https://{name}.portal.azure-api.net

    • Azure API Identifier – Leave it blank to create a new API in Azure API Management. Alternatively, if you want to update an existing API in Azure API Management, specify the API name here or in the x-azure-api-id key at the root level of your API definition.

      Tip: The API name can be found in the API settings in Azure:

      API name in Azure

      Click the image to enlarge it.

    • API URL Suffix – This suffix will be appended to the hostname of your API Management service instance to create a public URL for your API. As such, it must be unique within an API Management service instance.

      Note

      This option was added in v. 1.26.

      Examples:

      API URL Suffix

      Public base URL of the API in Azure

      myapi

      https://{instance}.azure-api.net/myapi

      myapi/reports

      https://{instance}.azure-api.net/myapi/reports

      If omitted, the suffix will be set to an empty string for OpenAPI 3.0 definitions, or the basePath value for OpenAPI 2.0 definitions.

    • Management API Access Token – Click Sign in with Microsoft. You will be prompted to log into your Azure account and authorize the connection with SwaggerHub.

      Notes for SwaggerHub On-Premise users:

      • If the "Sign in with Microsoft" button does not appear, follow these steps to configure Azure and your SwaggerHub On-Premise instance.

      • In versions prior to 1.21.0, paste the access token you generated earlier.

      Sign in with Microsoft

      Click the image to enlarge it.

    • Enable – Keep this check box selected for the integration to work. Unselect it to disable the integration temporarily.

  7. Click Create and Execute.

That’s it! Now, every time you save this version of the API, the definition is synced and updated in Azure API Management.

You can see the created or updated API in your Azure API Management portal:

API in Azure API Management

Click the image to enlarge it.

Troubleshooting

If there was a problem with pushing your API to Azure, you will see an Integration Error at the top of the SwaggerHub Editor. Below are some common errors you might run into and their solutions:

A definition must have a unique basePath section

All APIs in Azure API Management must have a unique basePath. This error means that an API with the same basePath already exists. To resolve the problem, specify another basePath in your API definition on SwaggerHub.

401 Unauthorized errors

This usually means that the access token has expired. To resolve the issue, open the integration settings and click Sign in with Microsoft. If there is no "Sign in" button, generate an access token manually as explained above and specify the new token in the integration settings.

See Also

In this section:
© 2024
Publication date: