Exposing applications on the Internet is always a complex matter. Usually, it requires some planning to be able to expose...
14 September 2023
Lire cet article en Français
How to Quickly Deploy Swagger Documentation for Your API in Azure
Creating and using Application Programming Interfaces (APIs) has become a major challenge for all IT companies. According to RapidAPI, it is estimated that 40% of the biggest companies (those with more than 10,000 employees) have more than 250 internal APIs, and more than 60% of the smaller companies use up to ten APIs internally.
Since this is the case, it is important to have documentation that is accessible and easy to distribute so APIs can be shared and adopted easily.
In this post, we’ll look at a few ways to deploy Swagger in your Azure infrastructure.
Requirements
Consider the following scenario: your organization has numerous APIs in Azure, and the API teams have registered each OpenAPI file on an Azure storage space. The specs container has been created in blob storage and holds all the OpenAPI files. The company wants to set up a dedicated resource group with a Swagger-based solution to expose its APIs to clients.
How to Deploy a Swagger Docker to Azure Application Service
To deploy Swagger on Azure, create an App Service to host a Swagger docker image.
To host a Swagger docker image (https://hub.docker.com/r/swaggerapi/swagger-ui), you must first create an App Service plan (for example, Linux/B1) and an App Service.
Next, add the URLs of the OpenAPI files on the storage account to the App Service application settings.
The URLS variable will contain the following value (replace <storage_account_name> with your storage account name):
After changing the application settings, you can go to your App Service domain and see that Swagger now shows the documentation for your APIs.
Updating Swagger
To add documentation for a new API, you must add the OpenAPI file for that API to the storage account. Next, you’ll need to update the URLS variable in the App Service application settings so that the changes take effect.
If an OpenAPI file on the storage account has been updated, all you have to do to see the latest version of the documentation is restart the App Service.
Pros and Cons of Deploying a Swagger Docker to Azure Application Service
| Pros | Cons |
| Ease of deployment: By deploying the docker image, you can focus solely on configuring Swagger. | Cost: The Azure resource is expensive (see Pricing). Setting up scaling can also cost extra. |
| Scalability: The App Service’s scalability can be used to adapt requirements based on load. | Variable performance: Other services that use the same App Service plan may limit the performance of an App Service. The performance of an application can also be affected by how the App Service plan is set up. |
| Security: This solution lets you use all the security services are available for an App Service (SSL/TLS certificates). |
Deploying Swagger as a Static Website
We can use a static site to host Swagger on Azure.
This requires a software factory such as Azure DevOps. We’ll use a GIT repository to host the source code (Azure Repos). The code will be deployed to the Static Web App using Azure Pipelines.
- Create a Static Web App instance in the resource group.
- You’ll need to retrieve the deployment token from Azure once the instance has been deployed.
- Create a project and a Git repository from Azure DevOps.
- Download the latest Swagger
- Extract the file and version the /dist folder in the Git repository (src/dist/).
- Change the url variable in the swagger-initialiser.js file to the following urls: [{ url: “https://<storage_account_name>.blob.core.windows.net/specs/petstore.yaml”, name: “Petstore” }, { url: “https:// <storage_account_name>.blob.core.windows.net/specs/zoom.yaml”, name: “Zoom” }],
- Version the change in Git. The file can now be deployed to a static site.
- Create a pipeline from Azure DevOps with the following code, but change the deployment token:
Once saved and executed, the pipeline will copy the contents of the /dist folder to the static web app.
You can check that your Swagger has been deployed by going to the domain of your Static Web App.
Updating Swagger
To add documentation for a new API, you must add the OpenAPI file for that API to the storage account. Then, add this new entry to the swagger-initialiser.js file in Git and version these changes. The pipeline will detect the changes automatically and update the Swagger.
If an OpenAPI file in the storage account has been updated, you just need to run the deployment pipeline again for the changes to take effect.
Pros and Cons of Deploying Swagger as a Static Website
| Pros | Cons |
| Ease of deployment: Unlike with App Service, there is no need to set up a static website. | Security: It is harder to set up authentication mechanisms in a static context. |
| Cost: Compared to the App Service equivalent, the Azure resource is inexpensive (see Pricing). | DevOps: Setting up a static website to host Swagger requires a software factory like Azure DevOps or Github to manage the Git repositories and deployment pipelines. |
| Performance: The static website benefits from static content caching, which makes it much faster to load Swagger and significantly improves its performance. |
Key Takeaways
In this post, we’ve seen how to implement Swagger in an App Service or a Static Web App in Azure. Authentication, price, and performance can all help you decide which solution is better for you.
Useful links:
Would you like to learn more or get some expert help? Contact us!
