What is OpenAPI specification?

This is a specification for machine-readable interface files for describing, producing, consuming and visualizing RESTful web services. Apparently, this was earlier part of the Swagger framework, it became a separate project sometime in 2016 overseen by the Open API initiative, an open-source collaboration project of the Linux Foundation. I am not trying to sound clever here. That’s all taken from wikipedia as I just wanted to give you an idea of what it is without having to leave this post.

What is Swagger?

Swagger is a popular tool for implementing the OPENAPI specification. So Open API is the official specification and Swagger is a set of tools that enable you to implement the specification. Swagger comes with a whole suite of tools, the core set of tools are:

  • Swagger Editor - api editor for designing APIs with the open api specification
  • Swagger UI - visualize openapi specification definitions in an interactive UI. You have probably used this if you have been working on developing REST APIs
  • Swagger Codegen - generates server stubs and client SDKs from OpenAPI specification definitions

Swagger also comes with other utilities to make your API development easier.

  • Swagger Parser - A standalone library for parsing Open API specifications from Java
  • Swagger Core - Java related libraries for creating consuming and working with OpenAPI definitions
  • Swagger Inspector - API Testing tool that lets you validate your APIs and generate OpenAPI definitions from an existing API.
  • SwaggerHub - An API design and documentation web app built for teams who work on OpenAPI

Swagger is not the only tool available for implementing OpenAPI specification. There are many others out there.

What are Azure Functions?

Azure functions is an event driven, compute-on-demand experience that extends the existing Azure application platform with capabilities to implement code triggered by events occurring in Azure or third party services.

In other words, it is Microsoft’s serverless offering, where you can focus on writing the application logic without worrying about hardware requirements as the platform allows you to scale using a slider based on the plan you choose.

Functions are generally executables that can be triggered by different types of events - http requests, blob storage changes, database changes, time intervals, queues, events, etc.

Microsoft allows you to write these functions in different languages - currently they support: C#, Java, Javascript, powershell, python, typescript, go and rust.

How do I get Swagger setup for my HTTP Azure Functions for a C# project?

There are two ways that I know of, to achieve this at the moment. Both the methods I am going to talk about are based on things I have tested on Azure Functions runtime version 3.

Using AzureExtensions.Swashbuckle

An open source nuget package that allows you to introduce a Swagger UI for your Azure function - AzureExtensions.Swashbuckle

This project has been around for a while and is pretty easy to get started with. You can clone the repository and open the Sample function in your visual studio to view how to describe the function so that the UI generates properly.

https://github.com/vitalybibikov/azure-functions-extensions-swashbuckle/tree/master/src/AzureFunctions.Extensions.Swashbuckle/TestFunction

Other instructions on getting started are already on the project README.

You can define request and response types using the following attributes:

  • RequestBodyType(typeof(YourType), "description")] HttpRequest req
  • ProducesResponseType(typeof(YourType), "description")]
  • SwaggerUploadFileAttribute("name", "description")] - to describe file upload in combination with HttpRequestMessage
  • QueryStringParameter - describe the params that you can pass to your URL

The examples actually give an insight into the different ways you can configure the Swagger UI.

A problem I ran into while trying to use this

If you have a host.json file, remember to not list your azure functions specifically in there. For example, if you have the "functions" section in the host.json, then remove it entirely so that the compiler can figure out the C# functions after the build.

{
  "version": "2.0",
  "functions": [
    "Function1",
    "SecondFunction"
  ], 
  ...
  ...
}

To read more about host.json file, head over to the microsoft docs reference page.

Polymorphism support in Swashbuckle

In my most recent project, I was trying to get a data contract (model) that had a Base class and several derived class to show up correctly in Swagger UI. I did not know until recently that this was already supported by Swagger. In order to demonstrate this I forked vitalybibikov’s AzureExtensions.Swashbuckle project and created a branch with the changes. I am not sure if the original author would merge my pull request. But I have created it anyway.

The changes required for this can be seen seen in commit-98446baf9004c14d3c019f3d25b872af4d3fb612

Using AzureFunctionsOpenApiExtension

This is an official Microsoft way of supporting OpenApi. This is still in preview and I feel after attempting to use it on a local azure function as a really cumbersome way to generate the swagger page. The official project can be found at https://github.com/Azure/azure-functions-openapi-extension

The README is pretty detailed and has links to get you started and all the sample code you need to try things out too. As I mentioned earlier, I felt like everything had to be explicitly declared in this case to generate the swagger page, unlike the earlier version. Maybe as time goes by, more improvements will be made to make the swagger UI generation easier. So keep an eye out.

I personally tried out the example in the documentation - https://github.com/Azure/azure-functions-openapi-extension/blob/main/docs/enable-open-api-endpoints-in-proc.md

The magic is made possible by the following nuget package: https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi

Apparently prior to this there used to be Justin Yoo(https://github.com/justinyoo)’s Swagger library for Azure Functions. You can read all about it on his post - https://devkimchi.com/2019/02/02/introducing-swagger-ui-on-azure-functions/

His nuget package is pretty popular - https://www.nuget.org/packages/Aliencube.AzureFunctions.Extensions.OpenApi/ And he might have contributed to the official microsoft extension too.

Useful references