With Azure Logic App you can build integrations with many products. One use case that I have investigating lately is to use Logic App as an API proxy for APIs where the original API needs adjustments to be consumer friend. The idea is to create a http-triggered logic app, call the backend API or multiple backend APIs and transform the returned data into a consumer friendly response.
In the specific project I’m working on the APIs that are being developed has to be hosted behind Azure API Management. API Management policies could also be used to call multiple APIs and transform data, but the experience of building policies is a bit lacking compared to building Logic Apps.
One problem I discovered when using the standard import functionality to get the Logic Apps into API management, is that the documentation in the API Management developer platform is really bad. The Logic App http trigger you can define the schema for if you use the code editor in logic app, you can then put description for the properties that becomes documentation in the API management developer portal. Here’s an example
However there is no way to define the schema for the return type of you Logic App Response action, which is equally important to have a properly documented API. So what to do then.
Two options
- Add the return type definitions and write descriptions of them inside the API Management portal
- Get an OpenAPI specification for the Logic App and extend that with the documentation that you want, and then import that into API Management instead of the direct option to import a Logic App
While option 1) is doable, option 2) provides a lot more flexibility, it allows you to combine different Logic App APIs into a single coherent API and you also have the OpenAPI specifications that can be used by other tools.
The question is how do get an OpenAPI specification for an Logic App? A great little hidden gem, is that there is actually an REST endpoint as part of the Azure Resource Manager, that allows you to generate an OpenAPI specification for an Azure Logic App. The endpoint is
https://management.azure.com/subscriptions//resourceGroups//providers/Microsoft.Logic/workflows//listSwagger?api-version=2016-06-01
The easiest way to call this API is to use the Azure CLI, like so
az rest -m POST -u https://management.azure.com/subscriptions//resourceGroups//providers/Microsoft.Logic/workflows//listSwagger?api-version=2016-06-01
If you sent a POST request to this endpoint you get a nicely auto-generated OpenAPI/Swagger specification for your Logic App. It will not have response types defined, but that is something that it manually can be extended with quite easily. Here’s the exported swagger file from my logic app