Now a days, many applications use Serverless APIs. And as we all know, basically, these serverless APIs are basically HTTP triggered Azure Functions. And when it comes to HTTP APIs, most of us prefer having a swagger page for the APIs so as to have the API documentation at one place.

In this article, we are going to create an Azure Functions project using Visual Studio. Then, this article will demonstrate how the swagger page works, which NuGet package is responsible and how to add new endpoints and add them to Swagger page.

Creating the Project

Let’s open Visual Studio and let’s select menu option to create a new project. On the new project Wizard, let’s search for Azure Functions project template as shown in the snapshot given below. Then click on Next button.

On the next screen of the wizard, we can provide the project name, project location and solution name. Optionally, we can also put the solution file in the project directory if we select the checkbox. After all inputs are provided, then click on Next button.

Next screen in the wizard is interesting. On the next screen, firstly, we can specify the .NET runtime version for this Azure Functions project. Azure Functions can be hosted as isolated process or in-process. This first input can decide this. For the sake of demo, let’s keep the default selected input.

Then the next input decides which kind of function app we want to create. This input decides the mode of communication (i.e. how inputs and outputs would be conveyed). There are various options – we can create HTTP Trigger, Queue trigger, Kafka trigger, Event Hub trigger, Event Grid trigger, RabbitMQ trigger, etc. In this article, we are going to focus on HTTP triggered functions.

Interestingly, the default selected option is Http Trigger with OpenAPI. If we keep this default selection and create the function app, the function app project will by default have a swagger page.

We can keep the default checkbox selected to use the Azurite for runtime storage account. Authorization level is to describe whether the functions can be invoked by anonymous callers or whether they should know the secret key. Let’s keep this value also to the default value.

Now, we can click on Create button and it will create the new project.

Run and Verify

In the Solution Explorer, we can see the newly created project. Let’s build and run this project. It would show the console window as shown in the snapshot given below.

The console window lists the endpoints and it also shows the URLs which would render the swagger page. I can navigate to that URL and it will present us the swagger page. Currently our project contains only a single endpoint, that’s why only one function is listed on the swagger page. We can try to call this endpoint via Swagger.

So, we have successfully created the project. But one question is still unanswered, how does it all work ? If we add new functions, we should know the answer to this question.

How does it work ?

It’s now time to understand how the swagger page works. It all works due to a NuGet package.

The NuGet Package

The NuGet package which is used by the project template is – Microsoft.Azure.WebJobs.Extensions.OpenApi. This package helps to render the OpenAPI document. This package is managed by Microsoft.

So, if you have an existing project of Http Triggered Functions and you want to add Swagger page to the project, you may want to add this NuGet package to the project.

The Attributes

This NuGet package mentioned above, provides various attributes which can be placed over the functions. Let’s have a look at the code of the single function, that was added by default when we created the project.

Here there are few commonly attributes used.

• FunctionName – this attribute sets the name of the function.
• OpenApiOperation – this attribute is to convey the extension (the NuGet package) to add an operation on the Swagger page. It takes the Operation Id, Tags, Summary, Description, etc. as inputs.
• OpenApiSecurity – this attribute is to mention the security scheme and security requirements for calling this function.
• OpenApiParameter – each instance of this attribute can be used to describe the parameter details.
• OpenApiResponseWithBody – this attribute can be used to specify the details about the probable response, which would contain body (i.e. contents). It can specify the type of the contents, response headers, status code, etc.
• OpenApiResponseWithoutBody – this attribute can be used to specify details about probable response that can be returned by function, which would not contain contents. For each status code, one instance of this attribute can be placed.
• OpenApiIgnoreAttribute – this attribute can be used to ignore a function from getting it documented in the Swagger page.

You can read about these (and some more attributes) on this GitHub page.

For existing projects, the NuGet page should be added to them and then the functions should be decorated with the above mentioned attributes. That should help to setup the initial version of swagger page. I believe, this setup can be further extended if any customizations, although I was not yet in need of those customizations.

Wrapping Up

I hope this article provides information about how Swagger page can be added to existing projects. I also hope that it provides idea about how the swagger page works with Azure Functions project. I hope you find this information helpful. Let me know your thoughts.