Post
Ask Question

How To Implement NSwag In ASP.NET Core Web API

Introduction

 
NSwag is a Swagger Open API 2.0 and 3.0 toolchain for the .NET, the .NET Core Web API, ASP.NET Core TypeScript, jQuery, Angular, Angular 2+, and many other platforms written in C# Programming Language. Swagger uses the JSON AND JSON Schema to describe the RESTful API the NSwag provides the tool to generate the Open API Specification from ASP.NET Core Controller and client-side NSwag provides the following capabilities. 
  • The Ability to utilize the Swagger UI and Swagger Generator.
  • Flexible Code Generation Capabilities
With NSwag, you do not need an existing API you can use third-party APIs that incorporate Swagger and generate the client implementation NSwag Allows you to Expedite the development cycle and easily adapt to API Changes.
 

Install The NSwag

 
From the Package Manager Console:
  • Go to the View> Other Windows > Package Manager Console
  • Execute the Command
Install-Package NSwag.AspNetCore
 
Package Manager Console
Figure 1
 
Execute the Command 
Figure 2
 

From Nuget Package Library

 
Install the Package using the Nuget package Library
  • Right-click on the Project Solution Explorer and select the ManageNuget Packages
  • Set the Package source to Nuget.org.
  • Ensure the prerelease option is enabled.
  • Enter the Name of the package NSwag.AspNetCore.
  • Select the latest version and hit the installation button.
Nswag has been Added 
Figure 3
 
Figure 4
 
Add and Configure the Middleware
 
Add the Middleware component to the startups class in the Startup.ConfigureServices of the project.
 
Startup.ConfigureServices
 
In the Startup. Configure services method, register the required Swagger services:
 
 
Figure 5
 
Registration of NSwag.NetCoreWebAPI Has been completed.
 
Figure 6
 
Code of the Project in Configure Method
 
In the Configure Method, enable the middleware for serving the generated Swagger Specification and Swagger UI.
  1. public void ConfigureServices(IServiceCollection services)  
  2.         {  
  3.             services.AddControllers();  
  4.             services.AddSwaggerDocument();  
  5.   
  6.         }  
NSwag Code Generation
 
Software Engineers can take the Advantage of NSwag’s Code Generation by choosing the following options:
  • NSwagStudio A window Desktop app for generating API Client Code in C#.
Install the NSwag Studio from the following repository:
 
Figure 7
  • The NSwag.CodeGeneration.CSharp Or NSwag.CodeGenertaion.typeScript NuGet Packages for Code Generation inside your project.
  • NSwag From Command-Line.
  • The NSwag.MsBuild Nuget Packages.
  • The Swagger OpenAPI a Visual Studio Connected service for generating API Client Code in C# or typeScript also generates a C# Controller for opening an API Service with NSwag.
Download the following extensions for Visual Studio:
 
Figure 8
 
Customize API Documentation
 
Swagger provides the options for documenting the object model to ease consumption of the web API. Swagger (Open API) is a language-agnostic specification for describing and documenting the REST API. Swagger Allows both the Machine and Developer to understand the working and capabilities of the Machine without direct access to the source code of the project the main objectives of swagger (Open API) are to:
  • Minimize the workload to connect with microservices.
  • Reduce the time needed to accurately document the microservice
API Information and Description
 
In the Startup.ConfigureServices method, a configuration action passed to the AddSwaggerDocument method adds information such as the author, license, and description.
  1. public void ConfigureServices(IServiceCollection services)  
  2.         {  
  3.             services.AddControllers();  
  4.             services.AddSwaggerDocument();  
  5.             services.AddSwaggerGen();  
  6.             services.AddSwaggerDocument(config =>  
  7.             {  
  8.                 config.PostProcess = document =>  
  9.                 {  
  10.                     document.Info.Version = "v1";  
  11.                     document.Info.Title = "Product API";  
  12.                     document.Info.Description = "A simple ASP.NET Core web API";  
  13.                     document.Info.TermsOfService = "None";  
  14.                     document.Info.Contact = new NSwag.OpenApiContact  
  15.                     {  
  16.                         Name = "Sardar Mudassar Ali Khan",  
  17.                         Email = string.Empty,  
  18.                         Url = "https://twitter.com/MudassarAliKhan"  
  19.                     };  
  20.                     document.Info.License = new NSwag.OpenApiLicense  
  21.                     {  
  22.                         Name = "Use under LICX",  
  23.                         Url = "https://example.com/license"  
  24.                     };  
  25.                 };  
  26.             });  
  27.   
  28.         }  
XML Commenting
 
To Enable XML commenting, follow the below steps:
  • Right-click the Project Solution folder and select the Edit > Your Project Name >.csproj file.
  • To manually enable it, add the below line in your project .csproj file:
Figure 9
  1. <PropertyGroup>    
  2.    <GenerateDocumentationFile>true</GenerateDocumentationFile>    
  3.    <NoWarn>$(NoWarn);1591</NoWarn>    
  4.  </PropertyGroup>     
Data Annotations
 
NSwag uses Reflection and the recommended return type for the web API actions is ActionResult<T> it can only target the return type by T and <T> Represents the generics in C# We can not automatically target other possible return types consider the following line of code as an example for above theory.
  1. [HttpPost]  
  2. public ActionResult<Product> CreateProduct item)  
  3. {  
  4.     _context.Products.Add(item);  
  5.     _context.SaveChanges();  
  6.     return CreatedAtRoute("Products", new { id = item.Id }, item);  
  7. }  
The Swagger Generator can now accurately describe this action and generated clients to know what they receive when calling the endpoints as a recommendation mark all the actions with these attributes.
 

Summary

 
NSwag is a Swagger Open API 2.0 and 3.0 toolchain for the .NET and .NET Core Web API, ASP.NET Core TypeScript, jQuery, Angular, Angular 2+, and many other platforms written in C# Programming Language. Swagger uses the JSON AND JSON Schema to describe the RESTful API the NSwag provides the tool to generate the Open API Specification from Asp.net Core Controller and client-side NSwag provides the following capabilities.
  • The Ability to utilize the Swagger UI and Swagger Generator.
  • Flexible Code Generation Capabilities
With NSwag, you do not need an existing API you can use third-party APIs that incorporate Swagger and generate the client implementation NSwag Allows you to Expedite the development cycle and easily adapt to API Changes.
 
Swagger (Open API) is a language-agnostic specification for describing and documenting the REST API. Swagger Allows both the Machine and Developer to understand the working and capabilities of Machine without direct access to the source code of the project the main objectives of swagger (Open API) are to:
  • Minimize the workload to connect with Microservice.
  • Reduce the Time Needed to accurately document the Microservice.
Swagger is the Interface Description Language for describing the RESTful APIS Expressed using JSON. Swagger is used to gathering with a set of open-source software tools to Design build documents and use Restful Web Services Swagger includes automated documentation code generation and test the generation. Three main components of Swashbuckle Swashbuckle.AspNetCore.Swagger is the Object Model and Middleware to expose swagger document as JSON End Points.
 
Swashbuckle.AspNetCore.SwaggerGen.Swagger Generator that builds Swagger Document Objects Directly from your routes controllers and models this package is combined with swagger endpoints middleware to automatically expose the Swagger JSON. Swashbuckle.AspNetCore.SwaggerUI is an Embedded version of the Swagger UI Tool it explains swagger JSON to build a rich customizable practical for explaining the Web API Functionality it includes a built-in test harnessed for the public Methods.
 

Conclusion

 
Open API Swagger is the best Open API for Documenting the Restful API. As a developer, I've had a great experience with Swagger for testing the restful API, sending the Complete JSON Object, and then getting the response professionally. It is easy to implement in an ASP.NET Core Web API Project. After the configuration, developers can enjoy the beauty of Swagger Open API.


Similar Articles