Swagger / OpenAPI Documentation

Swagger কী?

OpenAPI spec অনুযায়ী API documentation auto-generate। Frontend dev / consumer-দের জন্য।

Setup (Swashbuckle)

dotnet add package Swashbuckle.AspNetCore

// Program.cs
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c => {
    c.SwaggerDoc("v1", new OpenApiInfo {
        Title = "MyApp API",
        Version = "v1",
        Description = "RESTful API for MyApp",
        Contact = new OpenApiContact { Name = "Rahim", Email = "rahim@example.com" }
    });
});

var app = builder.Build();
if (app.Environment.IsDevelopment()) {
    app.UseSwagger();
    app.UseSwaggerUI(c => {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        c.RoutePrefix = string.Empty;   // root-এ Swagger UI
    });
}

XML Comments

<!-- .csproj -->
<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>1591</NoWarn>
</PropertyGroup>

// Program.cs
builder.Services.AddSwaggerGen(c => {
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFile));
});

// Controller
/// <summary>Returns all products</summary>
/// <param name="page">Page number</param>
/// <response code="200">Returns the list</response>
/// <response code="400">Invalid page</response>
[HttpGet]
[ProducesResponseType(typeof(List<ProductDto>), 200)]
[ProducesResponseType(400)]
public async Task<IActionResult> GetAll(int page = 1) => ...

JWT Authorization in Swagger UI ⭐

builder.Services.AddSwaggerGen(c => {
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme {
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "JWT Authorization. Enter: Bearer {token}"
    });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement {
        {
            new OpenApiSecurityScheme {
                Reference = new OpenApiReference {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            Array.Empty<string>()
        }
    });
});

Versioned Swagger

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

app.UseSwaggerUI(c => {
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");
});

NSwag (Alternative + Client Codegen)

dotnet add package NSwag.AspNetCore
// Generate TypeScript / C# client from OpenAPI

Minimal API + Swagger

app.MapGet("/products", () => products)
   .WithName("GetProducts")
   .WithOpenApi()
   .Produces<List<ProductDto>>(200);