An XML documentation comment is a structured C# comment that keeps method and parameter descriptions beside the code they describe. IDEs show these descriptions through IntelliSense, and OpenAPI tooling can reuse them for endpoint summaries and parameter documentation. section 11.5.3
Connect comments to an OpenAPI document in three steps:
- Enable documentation-file generation in the project file by setting GenerateDocumentationFile to true. section 11.5.3
- Configure Swashbuckle to read the XML file from the application base directory. section 11.5.3
- Add summary and param comments to a static or instance endpoint handler. section 11.5.3
/// <summary> /// Adds one to the provided value and returns it /// </summary> /// <param name="value">The value to increment</param> public int Increment(int value) => value + 1;
A small method shows the XML comment syntax and how a summary and parameter description sit directly above the C# declaration. section 11.5.3
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup>
This project-file setting makes the .NET SDK export the comments that Swashbuckle later consumes. section 11.5.3
builder.Services.AddSwaggerGen(opts =>
{
var file = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
opts.IncludeXmlComments(
Path.Combine(AppContext.BaseDirectory, file));
});
This startup configuration locates the generated XML file and includes its comments in the OpenAPI description. section 11.5.3
The approach reduces extra metadata calls and attributes, but it does not replace them completely. .NET 7 supports these comments only for static or instance method handlers, not lambda methods or local functions. section 11.5.3 section 11.7
