Introduction

Make sure that the DotNet SDK, along with the .NET CLI, is installed on the machine along with the VS Code editor.

Download .NET from the site.

These commands work across Windows, macOS, and Linux.

Then install the extension using VS Code,

extension >> c# (Microsoft), c# dev kit (Microsoft), c# extension (JosKreativ), SQL Server (mssql) (Microsoft)

Important commands

Step-1

Open the Integrated Terminal in VS Code.

You can do this from the top menu: Terminal > New Terminal

Step-2

C:\VSCode WebAPP\NETWebAPI >> dotnet add package Swashbuckle.AspNetCore

and check swagger reference dll files in bin folder.

Step-3

Open the Program.cs file and add the following lines before var app = builder.Build(); to register the Swagger generator:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Step-4

If you want to add custom information like a title and version, use this instead:

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

Step-5

Enable the Swagger middleware in Program.cs.

Add the following lines after var app = builder.Build(); to enable the middleware for serving the generated JSON document and the Swagger UI:

// Configure the HTTP request pipeline.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

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

Step-6

Run your application.

In the VS Code terminal, run your application with:

dotnet run

Step-7

View the Swagger UI.

Open a web browser and navigate to the Swagger UI endpoint:

http://localhost:/swagger

You should see the interactive documentation for your API.

Step-8

Optional: Enable XML Comments.

For detailed API documentation (e.g., method summaries, descriptions), you can use XML comments.

Enable XML documentation generation in your project file (.csproj):

Right-click on the project name in the VS Code Explorer and select Edit in .csproj.

Add the following property group:

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>

Step-9

Configure Swagger to use the XML file in Program.cs, within the AddSwaggerGen method configuration:

builder.Services.AddSwaggerGen(options =>
{
    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

Step-10

Run your application.

In the VS Code terminal, run your application with:

dotnet run

Summary

This guide explains how to set up Swagger in a .NET Web API project using VS Code. It covers installing required tools, adding the Swashbuckle package, configuring Swagger in Program.cs, enabling middleware, and optionally enhancing documentation using XML comments. This setup helps in generating interactive API documentation for better testing and understanding of endpoints.