Designing API from SwaggerHub to Azure API Management

When you develop a software, it is essential to create an API in order to enable applications to be connected to other systems. To understand an interface, you need to understand its structure and functions. SwaggerHub is a great platform to help you design and document your APIs. SwaggerHub lets you work as a team to define API interfaces. API definitions are written in the OpenAPI format and saved in the SwaggerHub Cloud.

In this article, I will explain how to setup the SwaggerHub integration feature, to synchronize your Azure API Management and SwaggerHub, which allows you to update APIs with any changes you make to the design in SwaggerHub. Thanks to this integration, you can design on your API definition on SwaggerHub.

Getting Started

Of course, you need an Azure subscription to use this integration. In this example, you should update API definitions in SwaggerHub only. First, I will create a very basic API by creating an API management service instance. Go to the Azure Portal, in the search bar, enter API Management Service and click on Create API Management Service:

Now, select an existing resource group or create a new one, then select the region and enter the resource name and organization name. Click create to create the API Management service. The creation process may take some time.

When the process is done, you should see your API Management Service with the ONLINE status.

Switch to the SwaggerHub portal : https://app.swaggerhub.com/. On this portal, I created an account and a very basic project PETSTORE, which is a well-known test project.

We will add integrate with our Azure API Management, click on Integration and Add New Integrations

Select Azure API Management in the drop down list and click Add

Now you need to enter some information about the integration, first enter a friendly name to identify this integration. This name will only appear in your SwaggerHub portal. Enter the name of your Azure API Management service instance (previously created in Azure):

We need to grant access to our Azure API Management Service, click on Sign in with Microsoft. If you are not global admin in Entra ID, you need to wait until an admin will approve the request :

Once the approbation is done, you should see something like that, then click Create and Execute

Now switch back to Azure portal and confirm it contains the API definition

Now we can make some changes in the API definition and check if the API is automatically updated in Azure or not. Go back to SwaggerHub portal and add a new parameter in the definition. In this case, I added a parameter named starwind.

Click save and go back to Azure portal to confirm the new parameter appears :

Great, the parameter is automatically updated in Azure.

Let’s send a request to test the API gateway in Azure. In the value field, enter available and click Send and see the response below

Looks good. Now, we can send a request from swagger. We just need to modify the following settings:

• Copy the base URL
• Clear the Subscription checkbox

Go back to SwaggerHub and paste the URL in your definition and select the server.

We can now send an API call to the API gateway, select Available and click Execute

Scroll down to check the result in the portal, we can confirm that the result is the same on SwaggerHub and Azure.

And to finish, we can also call the API from PowerShell using the following command: