Search
StarWind is a hyperconverged (HCI) vendor with focus on Enterprise ROBO, SMB & Edge

Designing API from SwaggerHub to Azure API Management

  • August 6, 2024
  • 7 min read
IT Production Manager. Nicolas is primarily focused on Microsoft technologies, he is a Microsoft MVP in Cloud and Datacenter Management.
IT Production Manager. Nicolas is primarily focused on Microsoft technologies, he is a Microsoft MVP in Cloud and Datacenter 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.

 

Une image contenant Graphique, cercle, clipart, Caractère coloré Description générée automatiquement

 

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:

 

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.

 

Select an existing resource group | Select the region and enter the resource name and organization name | Click create to create the API Management service

 

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

 

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.

 

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

 

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

 

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):

 

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 :

 

Azure API Management Service, click on Sign in with Microsoft

 

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

 

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

 

Now we can make some changes in the API definition and check if the API is automatically updated in Azure or not

 

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

 

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

 

Great, the parameter is automatically updated in Azure.

 

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

 

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 Now, we can send a request from swagger. We just need to modify the following settings

 

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

 

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

 

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.

 

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:

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

Hey! Found Nicolas’s insights useful? Looking for a cost-effective, high-performance, and easy-to-use hyperconverged platform?
Taras Shved
Taras Shved StarWind HCI Appliance Product Manager
Look no further! StarWind HCI Appliance (HCA) is a plug-and-play solution that combines compute, storage, networking, and virtualization software into a single easy-to-use hyperconverged platform. It's designed to significantly trim your IT costs and save valuable time. Interested in learning more? Book your StarWind HCA demo now to see it in action!