DEV Community

loading...
Cover image for Swagger and ReDoc for Documenting WEB API in .NET 5

Swagger and ReDoc for Documenting WEB API in .NET 5

caiosousa profile image Caio Sousa Updated on ・2 min read

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" });
   });
}
Enter fullscreen mode Exit fullscreen mode

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"));
}
Enter fullscreen mode Exit fullscreen mode

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.

Alt Text

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";
  });           
}
Enter fullscreen mode Exit fullscreen mode

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.

Alt Text

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.

Alt Text

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

Discussion (0)

pic
Editor guide