Integrating Swashbuckle Swagger with ASP.Net Core Web API

Screenshot from the tutorial

Integrating Swashbuckle Swagger with ASP.NET Core Web API

In the world of web development, creating APIs that are easy to understand and well-documented is crucial. One of the most popular tools for achieving this is Swashbuckle, which integrates Swagger UI with ASP.NET Core Web API. In this post, we’ll walk through the steps to set up Swashbuckle in an ASP.NET Core application, enabling you to generate beautiful API documentation effortlessly.

What is Swagger and Swashbuckle?

Swagger is an open-source framework that helps developers design, build, document, and consume RESTful APIs. It provides a standard way to describe your API using a JSON format known as the OpenAPI Specification (OAS).

Swashbuckle is a .NET library that seamlessly integrates Swagger with ASP.NET Core applications. It auto-generates Swagger documentation based on your API's controllers and models.

Prerequisites

Before we dive into the integration process, make sure you have:

• A basic understanding of ASP.NET Core
• Visual Studio or any compatible IDE installed
• .NET Core SDK installed on your machine

Step-by-Step Integration

Step 1: Create a New ASP.NET Core Web API Project

1. Open Visual Studio.
2. Create a new project by selecting ASP.NET Core Web Application.
3. Choose API as the project template and click Create.

Step 2: Install Swashbuckle.AspNetCore NuGet Package

To add Swashbuckle to your project, you need to install the necessary NuGet package. Follow these steps:

1. Open the Package Manager Console (Tools > NuGet Package Manager > Package Manager Console).

2. Run the following command:

   Install-Package Swashbuckle.AspNetCore
   

Alternatively, you can use the NuGet Package Manager GUI to search for Swashbuckle.AspNetCore and install it.

Step 3: Configure Swashbuckle in Startup.cs

Next, you need to configure Swashbuckle in your application. This is done in the Startup.cs file.

1. Open Startup.cs.

2. Add the following lines of code in the ConfigureServices method:

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

3. Now, add the middleware in the Configure method to serve the generated Swagger as a JSON endpoint:

   public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
   {
       if (env.IsDevelopment())
       {
           app.UseDeveloperExceptionPage();
       }
   
       app.UseRouting();
   
       app.UseAuthorization();
   
       // Enable middleware to serve generated Swagger as a JSON endpoint.
       app.UseSwagger();
   
       // Enable middleware to serve Swagger-UI (HTML, JS, CSS, etc.)
       app.UseSwaggerUI(c =>
       {
           c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
           c.RoutePrefix = string.Empty; // Set the Swagger UI at the app's root
       });
   
       app.UseEndpoints(endpoints =>
       {
           endpoints.MapControllers();
       });
   }
   

Step 4: Run Your Application

Now that you have set up Swashbuckle, it's time to run your application:

1. Start the application by pressing F5 or by clicking on the Run button in Visual Studio.
2. Navigate to http://localhost:<your_port>/ in your browser. If you set RoutePrefix to an empty string, you’ll see the Swagger UI.

Step 5: Exploring Swagger UI

The Swagger UI provides a user-friendly interface where you can see all your API endpoints, their descriptions, request parameters, and response types. You can even test your API directly from this interface:

• Click on any endpoint to expand it.
• Fill in any necessary parameters.
• Click Try it out to execute the request and see the response.

Customizing Swagger Documentation

While the default setup is great, Swashbuckle allows for further customization. Here are a few options:

Adding XML Comments

1. Enable XML comments in your project:

   • Right-click on your project > Properties > Build.
   • Check XML documentation file and specify a file name (e.g., MyApi.xml).

2. Modify ConfigureServices in Startup.cs to include XML comments:

   c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "MyApi.xml"));
   

Adding Header Parameters

You can also add global header parameters for your API. This can be done by modifying the AddSwaggerGen configuration:

c.OperationFilter<AddRequiredHeaderParameter>();

In this case, you would need to implement the AddRequiredHeaderParameter class to define the behavior.

Conclusion

Integrating Swashbuckle with your ASP.NET Core Web API is a straightforward process that can significantly enhance the accessibility and usability of your API. By following the steps outlined in this tutorial, you have not only set up API documentation but also learned how to customize it to meet your specific needs.

Now, you can focus on building robust APIs while Swashbuckle takes care of the documentation, making life easier for both you and your API consumers. Happy coding!

Another view from the tutorial

---

Connect with SkillBakery Studios

Explore more tutorials, tools, and resources:

• skillbakery.com
• Facebook
• X (Twitter)
• YouTube Channel

Posted by SkillBakery Studios