Creating a RESTful API with Automatic Documentation on Azure App Service

Introduction

The Azure platform provides a vast set of capabilities within a Platform as a service (PaaS) model to host web applications and services. The platform can offer more than just hosting to execute the logic in its applications; This also includes a series of robust mechanisms to manage all aspects of the life cycle of your web application as web services respectively.

These key features are of paramount importance for the creation of modern web applications through the Azure cloud as (PaaS).

When you are in the process of designing a software architecture based on a web application, one of the layers that you will need to implement is an API which allows the layers of your architecture to communicate with each other. Regardless of the architecture of your application, this is a good opportunity for you to implement a RESTful API for that intercom to happen with your respective documentation for the use of your API.

After reading this article, you can:

• Create a RESTful API application and deploy on Azure App service.
• Create a well-structured documentation for the API using open source tools.

Creating an API application with Azure App Service is a bit like creating a normal web application deployed as an App service. You may have the same options available for your API application as you have for a normal web application.

Create and Implement an API Application

To create a RESTful API application in Azure App Service, there are many ways, the most common ways are either through the Azure portal or directly from Visual Studio, in this case, we will make the example from Visual Studio 2019:

1. Run Visual Studio 2019 and select File > New > Project.
2. In the New Project dialog window, select ASP.NET Web Application (.NET Framework) within the cloud category and click Next.

   

3. In the New Project configuration dialog window, type the name of the project, in the physical location on the disk, select the type of .NET Framework to use and then click Create.

   

4. Select the Web API template in the new project configuration dialog window and then click Create.

   

   In this way, Visual Studio creates a new web API project with the following file structure in the file tree in the solution explorer:

   

Generate Automatic API Documentation using Swashbuckle

Swashbuckle is a very popular open source framework that consists of a large ecosystem of tools that work to design, build, document, and consume your RESTful API, which makes it the ideal alternative to create API documentation in a more automated way, the NuGet package is very well documented so you can review the documentation for more details by accessing the GitHub project by accessing the end of the article.

Swashbuckle is provided through a set of NuGet packages: Swashbuckle and Swashbuckle Core. Then follow these steps to add Swashbuckle to your API project:

1. Install the NuGet package, which includes Swashbuckle.Core as a dependency at the time of installation using the following command from the NuGet package console:

   Install-Package Swashbuckle

2. The NuGet package also installs an initial boot file or bootstrapper (App_Start / SwaggerConfig.cs) which enables Swagger paths when starting the API application using WebActivatorEx. You can also configure Swashbuckle options by modifying the GlobalConfiguration.Configuration.EnableSwagger extension method in the SwaggerConfig.cs file. You can also exclude from your API actions that have been marked with the obsolete decorative by adding the following configuration:
   C#

   public class SwaggerConfig
   {
         public static void Register()
         {
                 var thisAssembly = typeof(SwaggerConfig).Assembly;
                 GlobalConfiguration.Configuration
                 .EnableSwagger(c =>
                 {
                       ...
                       ...
   
                       //Set this flag to omit schema property descriptions for
                       //any type properties decorated with the Obsolete attribute
   
                       c.IgnoreObsoleteProperties();
   
                       ...
                       ...
   
                  });
          }
    }
   

3. Modify the actions of the controllers in your API project to include the swagger attribute to help the generator build the swagger metadata.

   

4. Swashbuckle is now configured to generate the Swagger metadata for your API endpoints with a simple user interface to explore the metadata.controller that is listed can produce the UI that is displayed by simply typing Swagger in the web browser bar followed by the web application.

   

Publish the RESTful API on Azure App Service

Up to this point, we already have the design of an API with the basics to connect with the other layers of your project, we also have a documentation that is already generated automatically, taking full advantage of all the metadata and definition of your API through the actions of its controllers, already prepared the above mentioned so far to implement your API application, you need to complete the publication from Visual Studio to Azure App Service to deploy your API project in the cloud.

Follow these steps to deploy your API project from Visual Studio:

1. Right-click on the project in the Visual Studio Solution Explorer and then click Publish.

   

2. In the publication dialog window, select App Service in the upper left, then Create New, then click publish to go to the Azure App Service settings.

   

3. The window will change and you will be sent to a more specific configuration where you must first write the name of the application to be deployed in Azure App Services, then select the subscription to which it is associated in your Azure portal.

   

4. Next, you must specify a resource group within the Azure cloud to which the web API application will be assigned as the Azure App Service resource.

   

5. If you do not own any resources or want to create a new resource, click on the new resource group name to be created.

   

6. This resource group usually allocates an expense capacity calculated through a scalable hosting plan with more or less capabilities, such as the use of RAM or the number of processors required for API execution, which by default select S1 (1 core, 1.75 GB RAM), in this case, we will lower API scalability for testing purposes and select a Free cost plan, this is to be shared and also for being an initial testing environment, when already If you want to scale the application more or change to a more quality or production environment, you can optimize it to an appropriate plan to efficiently execute your API project.

   

7. Once the entire API project environment is configured in Azure App Service, a publication profile is created in Visual Studio so that every time you want to run a deployment of your API with new changes, we simply run the publication using the button To post. Visual Studio proceeds to compile and try to upload all the files of the API project to the Azure cloud through Azure App service, so you can now access its API through the internet.

   

8. When the publication of your API project is finished, it will open in a new browser window where the initial publication web page will be displayed.

   

9. We will navigate to the Swagger documentation through the /Swagger route to see the details of the API documentation, in addition to test the REST methods already exposed through the API. For example, http://<YOUR-API-APP>.azurewebsites.net/swagger/.

   

Points of Interest

In this way, we can already have a RESTful application with a well-structured documentation in an automated way duly running through the Azure cloud through Azure App Service.

In this way, we can release our APIs through the Azure cloud in a more orderly, clean and with robust documentation for a good management maintenance of the API project that you want to create.

I will be glad to see in the comments any other example (real or only your ideas) of any case, either for the good use of documentation in the APIs as for any other case in the development of software and better supported by the Microsoft Azure cloud.

History

• 16^th February, 2020: V1
• 01^th Mayo, 2021: V1