Swagger/OpenAPI

1. What Problem Does Swagger Solve?

Old way: You write API. Then write Word doc: "GET /api/users returns User object". Doc gets outdated in 2 days.

Swagger way: You write API code. Swagger reads your C# and generates live docs + "Try it out" button automatically.

2. Enable Swagger - Already Done in .NET 8

When you created "ASP.NET Core Web API" project with "Enable OpenAPI support" checked, you already have it.

Check Program.cs:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer(); // Reads your controllers
builder.Services.AddSwaggerGen(); // Generates Swagger UI

var app = builder.Build();
if (app.Environment.IsDevelopment()) {
    app.UseSwagger(); // Generates /swagger/v1/swagger.json
    app.UseSwaggerUI(); // Serves /swagger UI
}
app.MapControllers();
app.Run();

Run F5 → Go to https://localhost:xxxx/swagger You’ll see all your controllers.

3. Make Swagger Useful - XML Comments + Examples

Problem: Swagger shows string name but not what "name" means.

Fix 1: XML Comments

1. Project → Properties → Build → Output → Check "Documentation file"
2. Program.cs → Add: builder.Services.AddSwaggerGen(c => { var xml = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xml)); });

Now add comments to your code:

/// 

/// Gets a restaurant by its unique ID
/// 
/// The restaurant ID. Must be > 0
/// The restaurant details
/// Restaurant found
/// Restaurant not found
[HttpGet("{id}")]
[ProducesResponseType(200)]
[ProducesResponseType(404)]
public ActionResult<Restaurant> Get(int id) {...}

Result: Swagger now shows description, params, possible responses. Frontend loves you.

1. Theory: OpenAPI vs Swagger

OpenAPI: The specification. A JSON file /swagger/v1/swagger.json that describes your API. This is the standard.

Swagger: Tools that use OpenAPI. Swagger UI = the HTML page. Swashbuckle = the .NET library that generates it.

Why it matters: That JSON file lets you auto-generate client code. Frontend runs 1 command: nswag → Gets full TypeScript client. No manual fetch calls.

2. Securing Swagger in Production

Theory: if (app.Environment.IsDevelopment()) hides Swagger in Prod by default. Good. You don't want hackers seeing all endpoints.

Senior move: Add auth to Swagger itself for staging:

app.UseSwagger();
app.UseSwaggerUI(c => {
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Zomato API V1");
    c.RoutePrefix = "docs"; // Access at /docs instead of /swagger
});

Then put /docs behind Azure AD login or IP whitelist.

3. Swagger Annotations - The Pro Setup

Make models show up clean:

public class Restaurant {
    /// 
Unique ID
    /// 101
    public int Id { get; set; }

    /// 
Restaurant name
    /// Domino's Pizza
    [Required]
    public string Name { get; set; }
}

Add JWT Auth button to Swagger:

builder.Services.AddSwaggerGen(c => {
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme {
        Description = "JWT Authorization header. Example: 'Bearer {token}'",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement {
        { new OpenApiSecurityScheme { Reference = new OpenApiReference {
            Type = ReferenceType.SecurityScheme, Id = "Bearer" }}, new string[] {} }
    });
});

Now Swagger has "Authorize" button. Frontend can test secured endpoints.