How to Build a Simple .NET 8 Minimal API with Swagger in 5 Minutes*

In this quick tutorial, you will learn how to build a simple REST API using .NET 8 Minimal API, complete with automatic API documentation using Swagger.

This guide is perfect for beginners who want to:

• Quickly prototype an API

• Learn Minimal APIs

• Add Swagger for API documentation and testing

The best part? You only need a single file to make it work.

---

Step 1 — Create a New Minimal API Project

Open your terminal and run the following commands:

dotnet new web -n SimpleSwaggerApi
cd SimpleSwaggerApi

What’s happening here:

• dotnet new web creates a minimal web app without unnecessary files or folders.

• You now have a clean starting point for your API.

---

Step 2 — Add Swagger to Your Project

By default, the minimal API template does not include Swagger.

To add Swagger, run:

dotnet add package Swashbuckle.AspNetCore

This installs Swashbuckle, the most widely used Swagger implementation for ASP.NET Core.

---

Step 3 — Create Your Minimal API with Swagger

Open the Program.cs file and replace its content with the following code:

var builder = WebApplication.CreateBuilder(args);

// Enable Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Enable Swagger UI in development mode
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

// Simple API endpoint
app.MapGet("/hello", () => "Hello from minimal API!");

// Run the application
app.Run();

What this code does:

• Adds Swagger services for API documentation.

• Sets up a simple GET endpoint at /hello.

• Runs the web app.

---

Step 4 — Run Your API

In the terminal, run:

dotnet run

You should see output similar to:

Now listening on: https://localhost:7123

---

Step 5 — Test Your API and Swagger UI

Open your browser and visit:

• API Endpoint: https://localhost:7123/hello

  You should see the message: "Hello from minimal API!"

• Swagger UI: https://localhost:7123/swagger

  Here, you can explore and test your API using the Swagger interface.

---

You Have Successfully Built Your API

At this point, you have:

• A working API endpoint

• Auto-generated API documentation via Swagger

• A clean, minimal codebase using just one file (Program.cs)

---

Why This Approach Works Well

• Great for learning and experimenting with ASP.NET Core Minimal APIs.

• Ideal for building prototypes and lightweight services.

• Easy to extend and maintain.