Asp.Net Web Api Adding Swashbuckle To Web Api Project Complete Guide

Last Update:2025-06-23T00:00:00 .NET School AI Teacher - SELECT ANY TEXT TO EXPLANATION. 8 mins read Difficulty-Level: beginner

Understanding the Core Concepts of ASP.NET Web API Adding Swashbuckle to Web API Project

ASP.NET Web API Adding Swashbuckle to Web API Project

Step-by-Step Guide

Prerequisites
- Ensure you have a project based on ASP.NET Web API.
- Have the NuGet Package Manager available in your Visual Studio.
Install Swashbuckle
- Navigate to the NuGet Package Manager in Visual Studio.
- Search for "Swashbuckle.AspNetCore" (for .NET Core) or simply "Swashbuckle" (for traditional Web API).
- Install the appropriate version corresponding to your project type.
Configure Swagger in the Startup File
- For ASP.NET Core, open Startup.cs.
- For traditional ASP.NET Web API, you might need to create a SwaggerConfig.cs file and modify the WebApiConfig.cs to initialize Swagger.

Register Swagger in Services

In Startup.cs, locate the ConfigureServices method.
Add the Swagger services using the AddSwaggerGen extension method.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
        // Optional: Configure XML comments
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

Enable Swagger UI

Still in Startup.cs, locate the Configure method.
Use the UseSwagger method to enable Swagger.
Use the UseSwaggerUI method to enable the Swagger UI.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });

    // Enable middleware to serve generated Swagger as a JSON endpoint
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
        // Optional: Set the default documentation page
        c.DefaultModelsExpandDepth(-1);
    });
}

Run the Application
- Build and run your project.
- Navigate to /swagger using your browser (e.g., http://localhost:5000/swagger).
- You should see the Swagger UI, which provides a comprehensive and interactive interface for exploring your endpoints.
Enhance the Documentation (Optional)
- You can customize the Swagger documentation by adding XML comments to your Web API methods and entities.
- Modify the startup configuration to include these XML comments as shown in the ConfigureServices section above.
Advanced Configuration (Optional)
- Customize the Swagger UI theme.
- Secure your Swagger Endpoint with OAuth2 or basic authentication.

Important Information

Version Compatibility: Ensure that the version of Swashbuckle matches your framework version.
Documentation: Include XML comments in your code to ensure that your documentation is complete and up-to-date.
Security: If your API requires authentication, configure the Swagger UI to handle securely exposing the API documentation.
Customization: Leverage Swashbuckle’s features to customize the Swagger UI and documentation to better fit your project's needs.

Online Code run

🔔 Note: Select your programming language to check or run code at

💻 Run Code Compiler

Step-by-Step Guide: How to Implement ASP.NET Web API Adding Swashbuckle to Web API Project

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

First, you need to create a new ASP.NET Web API project if you haven’t already:

Open Visual Studio.
Create a new project by selecting File > New > Project.
From the list of templates, select ASP.NET Core Web App (Model-View-Controller) or ASP.NET Core Web API depending on your needs.
Give your project a name and click Create.

If you select ASP.NET Core Web App (Model-View-Controller), you will need to add a new API Controller manually.

Step 2: Install Swashbuckle.AspNetCore

Swashbuckle can be added via NuGet Package Manager:

Right-click on your project in the Solution Explorer.
Select Manage NuGet Packages.
In the Browse tab, search for Swashbuckle.AspNetCore.
Install the latest version of the package.

Step 3: Configure Swashbuckle in `Startup.cs`

After installing the package, you need to configure Swashbuckle in the Startup.cs file.

a. Register Swashbuckle Services

In your Startup.cs file, locate the ConfigureServices method and add the following code to register Swashbuckle services:

using Microsoft.OpenApi.Models; // Don't forget to include this namespace

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(); // Ensure this line is present
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "YourAPI", Version = "v1" });
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath); // Optional: to include XML comments
    });
}

b. Enable Swagger and SwaggerUI Middleware

Next, you need to enable middleware for Swagger and SwaggerUI. Locate the Configure method and add these lines:

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

    app.UseRouting();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Step 4: Generate XML Comments (Optional)

To include XML comments in your Swagger documentation, you need to enable XML output in your project settings.

Right-click on your project in the Solution Explorer.
Select Properties.
Go to the Build tab.
Check the option XML documentation file.

This will generate an XML file with your project’s documentation at build time.

Step 5: Run Your Application

Now you can run your application and see the Swagger UI interface:

Press F5 or Ctrl + F5 to start the application.
Navigate to https://localhost:<port>/swagger (replace <port> with the actual port your application is running on).

You should see a UI that lists all your available API endpoints with details about their parameters, responses, etc.

Step 6: Customizing Swagger Documentation

You can further customize your Swagger documentation using attributes from System.ComponentModel.DataAnnotations.

For example, if you have a class Product, you can annotate it like so:

public class Product
{
    [Key]
    [Required]
    [Display(Name = "Product Id")]
    public int ProductId { get; set; }

    [Required]
    [StringLength(100)]
    [Display(Name = "Product Name")]
    public string Name { get; set; }

    [Required]
    [DataType(DataType.Currency)]
    [Display(Name = "Price")]
    public decimal Price { get; set; }
}

Also, you can use attributes in your controller actions to add more information:

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [ProducesResponseType(typeof(List<Product>), StatusCodes.Status200OK)]
    public IEnumerable<Product> Get()
    {
        return new List<Product>
        {
            new Product { ProductId = 1, Name = "Laptop", Price = 999.99M },
            new Product { ProductId = 2, Name = "Smartphone", Price = 799.99M }
        };
    }

    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    public IActionResult Post([FromBody] Product product)
    {
        // Logic to add product
        return CreatedAtAction(nameof(Get), new { id = product.ProductId }, product);
    }
}

Step 7: Test Your API Endpoints

The Swagger interface provides a way to test your API endpoints directly from the browser. You can call GET and POST methods and see the responses.

Conclusion

By following these steps, you’ve successfully integrated Swashbuckle into your ASP.NET Web API project, generating comprehensive API documentation automatically. This will help make your API easier to understand and consume. If you need more advanced configurations, Swashbuckle’s documentation on GitHub is a great resource!

Top 10 Interview Questions & Answers on ASP.NET Web API Adding Swashbuckle to Web API Project

Top 10 Questions and Answers on ASP.NET Web API Adding Swashbuckle to Web API Project

1. What is Swashbuckle?

2. How do I add Swashbuckle to an existing ASP.NET Web API project?

Answer: To integrate Swashbuckle into your existing ASP.NET Web API project, you need to install the Swashbuckle.AspNetCore package via NuGet Package Manager. You can also use the Package Manager Console with the following command:

Install-Package Swashbuckle.AspNetCore

After installation, register Swagger and the Swagger Generator in Startup.cs:

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

Then, modify the Configure method to enable middleware for serving the generated Swagger document and the Swagger UI:

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

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

3. Do I need to restart my project after adding Swashbuckle?

Answer: Generally, adding Swashbuckle doesn’t require a restart, but it’s always a good practice to restart your project to ensure all changes are applied correctly and dependencies are loaded properly.

4. Can I customize the Swagger documentation provided by Swashbuckle?

Answer: Yes, Swashbuckle offers extensive customization options. This includes customizing the title and description of your API, defining custom XML comments for more detailed operation descriptions, and setting up security definitions. For example, to include custom XML comments, you can configure Swagger like this:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo 
    { 
        Title = "Your API Name", 
        Version = "v1",
        Description = "This is your API for testing."
    });

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

5. How do I add authorization to Swagger?

Answer: To add authorization support in Swagger, you need to configure Swagger Gen with proper authentication details and then enable the UI to accept the tokens. For JWT Bearer token authentication, you'd use:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });

    // Define the JWT Security Scheme
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey
    });
    
    // Set up security requirements
    c.AddSecurityRequirement(new OpenApiSecurityRequirement()
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                },
                Scheme = "oauth2",
                Name = "Bearer",
                In = ParameterLocation.Header,

            },
            new List<string>()
        }
    });
});

Additionally, in Configure, you need to ensure Swashbuckle uses this security definition.

6. How can I display XML comments in Swagger?

Answer: To display XML comments in Swagger documentation, you must generate XML documentation files during the build process. First, navigate to your project properties and select the "Generate documentation file" option under the Build section. Then, update the AddSwaggerGen configuration in Startup.cs to include XML comments, as shown in the previous question.

7. Can Swashbuckle be configured to use multiple versions (tags) of my API?

Answer: Absolutely! Swashbuckle supports multi-versioning in APIs. This requires configuring different documentations in AddSwaggerGen method. Here's how to do it for two versions:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "Your API Name", Version = "v2" });
});

And correspondingly in the Configure method:

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "Your API Name V2");
});

8. Why am I seeing no responses or empty documentation for my API methods?

Answer: Empty documentation most often stems from missing XML comments above your API methods, controllers, or parameters. Make sure these comments are added and that the XML documentation file is being referenced in the AddSwaggerGen method, as outlined previously.

9. How to test the API through Swagger UI?

Answer: Once Swashbuckle is configured and running, navigate to /swagger in your browser to access the Swagger UI. From here, you can explore the available endpoints, click on them to see further detail, and even execute sample requests by filling out input values and clicking the "Try it out" button. Responses from your API are then displayed below.

Asp.Net Web Api Adding Swashbuckle To Web Api Project Complete Guide