Azure APIManager + Swagger(OpenAPI) = Awesome
Microsoft Azure has supported Swagger specification for API documentation which is also referred as OpenAPI v2.0, for quite some time now in many of its services. We have been using APIManager heavily as the entry point to our service fabric micro services. APIManager (APIM) provides a lot of benefits for all kind of public facing APIs which otherwise is always a major developer concern.
We heavily use AzureResourceManager (ARM) templates for idempotent automated deployment of our infrastructure in Azure as part of our CI/CD pipeline. Microsoft has a good quick start template repository on GitHub for variety of ARM Templates. This has mostly been a great experience. Emphasis is on mostly because ARM has some drawbacks too. ARM is very good for what it does but still it is evolving constantly.
In our specific case of APIM, we constantly find that the documentation of the API in the ARM template is a tedious developer experience. Note that APIM has a developer portal where the consumer of the API can login and see the APIs with additional information like the response types, examples and a test bed to play with sample request and response.
All this is facilitated by the information put in the ARM template. The ARM templates are JSON format files. Adding any API documentation and sample to it requires escaping of characters, adding “\n” manually for the new lines etc. This is not a very good experience. Other way we do sometimes is to have this documentation done in the Azure portal itself for a mock API and then generate the string in the blade by going to Automation Script under settings.
Azure APIManager now provides ability to import Swagger files through powershell for the documentation of the APIs. This greatly reduces the pain of developers because the OpenAPI standard is the industry standard for doing the API documentation and Swagger provides an elegant interface for it. You may see a sample swagger API documentation here. Do note that there are some limitations at the moment while trying to import the Swagger file in Azure APIM.
We are experimenting if we can use swagger effectively to decouple the infrastructure concerns with the API documentation and in turn provide a better and richer document for our API consumers. You can also import/export the swagger format json file from the Azure portal but below I will discuss the way to import the swagger file through powershell because that would be the most suitable use case in a development team.
You may import the Swagger file with powershell using Import-AzureRmAPIManagementApicommandlet. Read through the microsoft link below.
Swagger file import would create the API Operations (endpoints) for you with the required input parameters and the sample documentation. It would not apply the policies to your API (e.g cors, inbound/outbound policies etc.). It will also not associate products to your API. For such tasks, you may require to invoke additional Powershell commandlets or you can use ARM Templates in combination with Swagger.
Not really an elegant solution you were hoping for ¯\_(ツ)_/¯ but still in some ways it is better than fiddling with the ARM for creating rich documentation around your API. This decouples the concerns of documentation vs the infrastructure.
I hope this helps you improvise your development workflow while dealing with deployment of your APIs on Azure APIM.
