All 15 API Documentation with Swagger/OpenAPI questions
More in API Documentation with Swagger/OpenAPI
What is OpenAPI, and how does Swashbuckle generate an OpenAPI document for an ASP.NET Core API? How do you document multiple response types (like 200, 400, 404) for a single endpoint in Swagger using ProducesResponseType? How do you organize and group endpoints in Swagger UI by tags or API version? How do you customize example values shown in Swagger UI for request and response bodies? How do you validate that an API's actual behavior matches its published OpenAPI specification, preventing documentation drift? How do you version your OpenAPI documentation to reflect API versioning implemented via the Asp.Versioning library? How do you add global metadata (like a description, contact info, and license) to the top level of a generated OpenAPI document? How do you document authentication requirements (like a JWT bearer token) in Swagger UI so users can test authenticated endpoints interactively? How does the newer built-in Microsoft.AspNetCore.OpenApi package (introduced in .NET 9) differ from the third-party Swashbuckle package? How would you exclude specific endpoints or entire controllers from appearing in the generated Swagger documentation?
Advertisement
ASP.NET Core › API Documentation with Swagger/OpenAPI

How do you add XML documentation comments to enrich generated Swagger documentation with descriptions?

Intermediate

Answer

Enabling GenerateDocumentationFile in the .csproj causes the compiler to extract /// XML doc comments into a .xml file, which Swashbuckle can be configured to read via IncludeXmlComments(), populating endpoint summaries, parameter descriptions, and response descriptions in the generated OpenAPI document directly from your existing code comments.
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

/// <summary>Gets a product by its ID.</summary>
/// <param name="id">The product's unique identifier.</param>
[HttpGet("{id}")]
public IActionResult GetProduct(int id) { ... }

builder.Services.AddSwaggerGen(c => {
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "MyApi.xml"));
});
Real-world example A team writes XML doc comments primarily for IntelliSense during development, then discovers those same comments automatically populate meaningful endpoint descriptions in Swagger UI, giving API consumers documentation for free without duplicated effort.

Common follow-ups: What happens if XML comments are missing for some endpoints?;How do you document response types beyond just the success case?

API Documentation with Swagger/OpenAPI;Controllers vs Minimal APIs
All 15 API Documentation with Swagger/OpenAPI questions