An XML documentation file is a compiler-generated collection of structured descriptions extracted from triple-slash XML comments in C# source code. Swashbuckle can read it and display endpoint, parameter, and return-value explanations in SwaggerUI. section 11.2.2 section 11.2.3
Enable XML documentation for an API with these implementation steps:
- Add triple-slash comments above action methods, including <summary>, <param>, and <returns> elements. section 11.2.3
- Set GenerateDocumentationFile to true in the project file so the compiler creates an XML file during every build. section 11.2.3
- Choose whether to suppress CS1591 warnings for undocumented public types and members with the NoWarn project setting. section 11.2.3
- Configure Swashbuckle to derive the XML filename from the assembly and combine it with the application base directory. section 11.2.3
// ... existing code <ItemGroup> <Protobuf Include="gRPC/grpc.proto" /> </ItemGroup> <PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup> // ... existing code
Use the project-file configuration to generate the XML documentation artifact. section 11.2.3
using System.Reflection; #1
// ... existing code
builder.Services.AddSwaggerGen(options =>
{
var xmlFilename = #2
$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
options.IncludeXmlComments(System.IO.Path.Combine( #3
AppContext.BaseDirectory, xmlFilename));
// ... existing code
Use the assembly name and application base directory to let Swashbuckle locate the generated file. section 11.2.3
