Swagger / OpenAPI Documentation in ASP.NET Core

Introduction

Swagger UI (OpenAPI) lets ShopNest partners explore and test the Product API without reading source code — essential for developer-facing APIs and campus project demos.

After this article you will

• Configure Swashbuckle in ASP.NET Core
• Add XML doc comments to controllers
• Document JWT bearer security in Swagger
• Support API versioning in Swagger UI
• Know Scalar as modern UI alternative

Prerequisites

• Article 37 — API Versioning
• ShopNest with EF Core and auth from Modules 2–4

Concept deep-dive

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "ShopNest API", Version = "v1" });
    var xml = Path.Combine(AppContext.BaseDirectory, "ShopNest.Api.xml");
    options.IncludeXmlComments(xml);
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT"
    });
    options.AddSecurityRequirement(new OpenApiSecurityRequirement { ... });
});

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "ShopNest v1"));
}

Enable XML docs in .csproj: <GenerateDocumentationFile>true</GenerateDocumentationFile>

/// summary comments appear in Swagger for each endpoint. Scalar — drop-in modern alternative to Swagger UI.

Hands-on — ShopNest Developer-Facing API

1. Add Swashbuckle; browse /swagger in Development.
2. XML comments on ProductsController actions.
3. Authorize button — paste JWT from login endpoint.
4. Generate C# client with NSwag or OpenAPI Generator (optional).

Common errors & best practices

• Swagger exposed in Production without auth — disable or protect with policy.
• Missing XML file path — build fails silently without comments.

Interview questions

Q: OpenAPI vs Swagger?
A: OpenAPI is the spec; Swagger is tooling (UI + codegen) implementing it.

Q: Swashbuckle vs NSwag?
A: Both popular; Swashbuckle most common in ASP.NET Core tutorials.

Summary

• Swagger documents REST contracts for humans and codegen
• JWT security definition enables Try-it-out with auth
• XML comments improve partner developer experience
• Disable or lock down Swagger in production

Previous: API Versioning
Next: Input Validation in Web APIs

FAQ