Swagger and ReDoc for Documenting WEB API in .NET 5

Introduction

Lets say you have a WEBAPI and would like to update the documentation of that API automatically. Frameworks such as swagger and Redoc might be a good approach since they both have nuget packages available within the Visual Studio IDE for a quick and easy setup.

Setup

Right Click the WebAPI Project and click Manage Nuget Packages, to install the following packages:

• Swashbuckle.AspNetCore
• Swashbuckle.AspNetCore.Swagger
• Swashbuckle.AspNetCore.ReDoc

Swagger Configuration

In the Starup.cs file include SwagerGen in the ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
   services.AddSwaggerGen(c =>
   {
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApiDevoTo", Version = "v1" });
   });
}

Include the middleware in the Configure method:

 public void Configure(IApplicationBuilder app, 
                       IWebHostEnvironment env)
{
   app.UseSwagger();
   app.UseSwaggerUI(c => 
   c.SwaggerEndpoint("/swagger/v1/swagger.json", 
                     "WebApiDevoTo v1"));
}

Run the application and the if you created new WebAPI Project with views and controllers the weather forecast should be available as shown in the figure below.

ReDoc Configuration

Include the ReDoc middleware in the Configure method:

 public void Configure(IApplicationBuilder app, 
                       IWebHostEnvironment env)
{           
  app.UseReDoc(c =>
  {
    c.DocumentTitle = "REDOC API Documentation";
    c.SpecUrl = "/swagger/v1/swagger.json";
  });           
}

If you run the application by default the swagger interface will appear navigate to {localhost}/api-docs to see the ReDoc interface as the figure below.

To enable ReDoc to run as default set the launch browser of your WebApi to api-docs, to do this right click the WebApi project > Properties > Debug.

Swagger X ReDoc [Free Version]

	Swagger	ReDoc
Open Source	Yes	Yes
OpenAPI Specification	Yes	Yes
Allows embedded HTML/CSS/JS	Yes	Yes
Try-Me Functionality	Yes	No
Layout with sidebars (Three panel)	No	Yes

Conclusion

To rapidly expose your applications API frameworks such as ReDoc and Swagger is definitely a quick and practical solution. Swagger and ReDoc both offer a free and paid version and should be explored to adjust the user’s needs. Please comment on the resources you use for documenting your API.

References

• Swagger
• ReDoc