Swagger/OpenAPI: versioning and including XML doc comments

APIs without OpenAPI documentation require developers to guess endpoint shapes. Large APIs with many endpoints become unmanageable when swagger is misconfigured and shows auto-generated names without descriptions.

Configure Swagger with XML comments and multiple versions:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

    // Include XML doc comments
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);

    // Bearer token auth
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer"
    });
});

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Enable XML docs in .csproj:

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>

Swashbuckle reads XML doc comments generated by the C# compiler and embeds them in the OpenAPI JSON. Without GenerateDocumentationFile, no XML file is produced and IncludeXmlComments fails silently.