ASP.NET Core  

Swagger Configuration in ASP.NET Core Web API using VS Code

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.

  • dotnet --version: Prints the version of the .NET SDK that is currently in use by the dotnet command.

  • dotnet --list-sdks: Displays a list of all installed .NET SDK versions and their installation paths.

  • dotnet --list-runtimes: Displays a list of all installed .NET runtimes (including ASP.NET and Windows Desktop runtimes) and their installation paths.

  • dotnet --info: Prints detailed information about the .NET installation and environment, including the OS, runtime identifier (RID), installed SDKs, and runtimes.

Then install the extension using VS Code,

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

Important commands

  • dotnet --help

  • dotnet new

  • dotnet new list

  • dotnet new webapi

  • dotnet new webapi -controllers --force

  • dotnet build

  • dotnet run

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.

Membership not found