The Desired Functionality
Quite a lot of the components we create in Azure are Azure Functions. Azure Functions have a lot of advantages, they are serverless, scale easily, and there are many different triggers and bindings available out-of-the-box (see https://docs.microsoft.com/nl-nl/azure/azure-functions/functions-triggers-bindings?tabs=csharp#supported-bindings). One of the triggers is the HTTP trigger which allows us to create serverless APIs.
However there is one downside to creating a HTTP triggered Azure Function – there is no built in support to create an OpenAPI specification document so that it can be published in the Swagger UI. This can make it tricky when you want to implement an Azure Function into your service but don’t know exactly what the definition of the request and response is.
I discovered that it’s possible to implement the Swagger UI in a HTTP triggered Azure Function.
How To Implement This
There are a few ways to implement this, but we found the easiest way to do so is to use the Aliencube.AzureFunctions.Extensions.OpenApi nuget package (see https://github.com/aliencube/AzureFunctions.Extensions/blob/dev/docs/openapi.md).
After adding this package to your project you can add OpenApi attributes to your Function method, for example:
Also make sure you add the appropriate configuration to your host.json and local.settings.json, for example:
local.settings.json
host.json
If you now run your Function locally the Swagger UI will be available at http://localhost:{port}/api/swagger/ui:
Additionally, the OpenAPI specification documents are available at:
- http://localhost:{port}/api/openapi/v2.json
- http://localhost:{port}/api/openapi/v2.yaml
- http://localhost:{port}/api/openapi/v3.json
- http://localhost:{port}/api/openapi/v3.yaml
Conclusion
By using the Aliencube.AzureFunctions.Extensions.OpenApi package, with just a few lines of code and some minor changes to your settings file, you are now able to publish your OpenAPI specification in the Swagger UI!
Many thanks to the creators of the Aliencube.AzureFunctions.Extensions package, it really saved us a lot of time and our HTTP triggered Azure Functions are now clearly documented.
Subscribe to our RSS feed