Mastering Swagger in ASP.NET Core (.NET 6/7/8)

As backend developers, we build APIs daily, but documenting them often feels like a chore. That’s where Swagger and OpenAPI shine. With just a few lines of code in .NET, we get interactive, auto-generated documentation that’s developer-friendly, testable, and even client-shareable.

In this article, I’ll show you how to integrate Swagger into your ASP.NET Core project using Swashbuckle, customize it, and follow best practices — all based on the latest .NET versions.

📘 What is Swagger (OpenAPI)?

Swagger is a toolset for documenting and testing REST APIs, built on the OpenAPI Specification — a standard way to describe HTTP APIs.

In .NET, Swagger is typically implemented using Swashbuckle.AspNetCore NuGet package, which:

• Generates OpenAPI docs
• Hosts Swagger UI
• Allows customization and security

🛠️ Step-by-Step: Add Swagger in ASP.NET Core (Latest Version)

Let’s walk through setting it up in a clean .NET 8 Web API project.

✅ 1. Install Swashbuckle

In your terminal or NuGet Package Manager:

dotnet add package Swashbuckle.AspNetCore

✅ 2. Configure Swagger in Program.cs

var builder = WebApplication.CreateBuilder(args); 

// Add services 
builder.Services.AddControllers(); 
builder.Services.AddEndpointsApiExplorer(); 
builder.Services.AddSwaggerGen(c => 
{ 
    c.SwaggerDoc("v1", new OpenApiInfo 
    { 
        Title = "My API", 
        Version = "v1", 
        Description = "Sample Swagger setup in ASP.NET Core" 
    }); 
}); 

var app = builder.Build(); 

// Use Swagger middleware 
if (app.Environment.IsDevelopment()) 
{ 
    app.UseSwagger(); 
    app.UseSwaggerUI(c => 
    { 
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); 
    }); 
} 

app.UseAuthorization(); 
app.MapControllers(); 
app.Run();

🧪 What You Get

Navigate to

📍 https://localhost:{port}/swagger

You'll see

• A list of your endpoints
• Sample input/output models
• Ability to test requests right from the browser

🧰 Customize Swagger UI

Make it yours by customizing the title, version, or adding a logo.

app.UseSwaggerUI(c => 
{ 
    c.DocumentTitle = "My Custom API Docs"; 
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1"); 
    c.InjectStylesheet("/swagger-ui/custom.css"); // Optional custom styling 
});

You can create wwwroot/swagger-ui/custom.css to style your UI.

📝 Add XML Comments to Improve Docs

Want your method and model summaries to show up?

1. Enable XML documentation in your .csproj

   <PropertyGroup> 
       <GenerateDocumentationFile>true</GenerateDocumentationFile> 
   </PropertyGroup>

2. Update Swagger config

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

Now, add XML comments in your code:

/// <summary> 
/// Gets all products 
/// </summary> 
[HttpGet] 
public IActionResult GetProducts() { ... }

🔐 Secure Swagger for Production (Optional)

You don’t always want Swagger open in production.

if (app.Environment.IsDevelopment()) 
{ 
    app.UseSwagger(); 
    app.UseSwaggerUI(); 
}

You can also password-protect it or restrict by role using middleware or environment variables.

✅ Best Practices for Swagger

Best Practice	Why it Helps
Use meaningful summaries/descriptions	Improves readability for consumers
Secure Swagger UI in production	Prevents public access to internal API details
Group endpoints using tags	Organizes large APIs
Document models using [DataAnnotations]	Makes your schema clear and predictable
Sync Swagger version with API version	Avoids confusion when releasing changes

👋 Conclusion

Swagger is more than just documentation — it's a gateway for developers to understand, test, and adopt your API quickly. In modern .NET (6, 7, and 8), integrating Swagger with Swashbuckle is easy, powerful, and highly customizable.

Whether you're building public APIs or internal services, a well-documented API builds confidence, reduces onboarding time, and improves quality.

In my next article, I’ll cover advanced Swagger use cases like grouping, versioning, and JWT token testing.

Until then — happy documenting!