Swagger in ASP.NET Core

If you want to have open API standards and API documentation easy and almost no code, you should try Swagger in ASP.NET Core.

Whаt is Swаgger?

Swagger is a language-independent specification for describing REST APIs. The Swagger project was given to the OpenAPI Initiative project and is now called Open API. Both names are used interchangeably, but Open API is preferred. It allows computers and users to understand the features of a service without any direct access to the implementation (source code, network access, documentation). One of the goals is to limit the amount of work needed to connect dissociated services. Another goal is to reduce the time needed to document a service accurately

The Swagger specification

For Swagger to work, and even more so for the graphical documentation interface called Swagger UI, a swagger.json file must exist (at least at least virtually).

This file is usually in ASP.NET generated by a third-party component that retrieves the code documentation in XML format and extracts a Json documentation.

It describes the features of your API and how to access it with HTTP. It manages the Swagger UI and is used by the toolchain to enable discovery and client code generation

in ASP.NET The component to use was the Swashbuckle component

Swashbuckle has three main components:

• Swashbuckle.AspNetCore.Swagger: Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.
• Swashbuckle.AspNetCore.SwaggerGen: Swagger generator that creates SwaggerDocument objects directly from your routes, controllers, and models. It is typically associated with Swagger endpoint middleware to automatically expose Swagger JSON.
• Swashbuckle.AspNetCore.SwaggerUI: Embedded version of the Swagger IU tool. She interprets Swagger JSON to generate a complete and customizable experience to describe the functionality of the web API. It includes integrated testing workshops for public methods

For more information https://docs.microsoft.com/en-US/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.1&tabs=visual-studio%2Cvisual-studio-xml

in ASP.NET core 2 it is more recommended to use the NSwag component

Using NSwag with ASP.NET Core middleware requires the NuGet NSwag.AspNetCore package. The package consists of a Swagger Generator, Swagger IU (v2 and v3) and ReDoc IU

To use the package

1. Reference the NSwag.AspNetCore package
2. In Startup Call the Middleware Swagger

аpp.UseSwаgger (typeof (Stаrtup) .Assembly, settings =>
 {
     settings.PostProcess = document =>
     {
         document.Info.Version = "v1";
         document.Info.Title = "Title";
         document.Info.Description = "API Description ";
         document.Info.TermsOfService = "TermsOfService ";
         document.Info.Contаct = new NSwаg.SwаggerContаct
         {
             Nаme = "Arash Pakzad",
             Emаil = "info@parsstudent.com",
             Url = ""
         };
         document.Info.License = new NSwаg.SwаggerLicense
         {
             Nаme = "",
             Url = ""
         };
     };
 });

 аpp.UseMvc ();
 }

To install the Swagger-ui client

Call the SwaggerUi3 middleware

app.UseSwaggerUi3 (typeof (Startup) .GetTypeInfo (). Assembly, settings =>
{
    settings.GeneratorSettings.DefaultPropertyNameHandling = NJsonSchema.PropertyNameHandling.CamelCase;
});

To test the application call the URL http: //yourhost/ swagger

You can use ReDoc to generate the documentation interface. This provides a better graphical interface

Just replace app.UseSwagger with app.UseSwaggerReDoc

using Swagger in ASP.NET Core is super easy and as you saw, there is just very minimalistic work you have to do.