.NET Core 8 API如何在Swagger JSON中包含控制器XML注释？

如果你不想生成独立的XML文件来供Swashbuckle读取注释，可以将XML注释直接嵌入到程序集内部，这样既保留了注释读取能力，又不会产生额外的XML文件。具体步骤如下：

1. 修改项目配置，嵌入XML注释 #

打开你的API项目的.csproj文件，添加以下配置到<PropertyGroup>节点中：

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn> <!-- 可选：关闭"缺少XML注释"的编译警告 -->
<EmbedDocumentation>true</EmbedDocumentation> <!-- 核心配置：将XML注释嵌入程序集 -->

这个配置会让编译器生成XML注释，并直接嵌入到输出的DLL文件中，不会在输出目录生成单独的.xml文件。

2. 在Swagger配置中读取嵌入的注释 #

在Program.cs的AddSwaggerGen配置里，通过程序集获取嵌入的XML资源流，传递给IncludeXmlComments方法：

var currentAssembly = typeof(Program).Assembly;
var embeddedXmlName = $"{currentAssembly.GetName().Name}.xml";

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("my_api_name", new OpenApiInfo { Title = "你的API名称", Version = "v1" });

    // 读取嵌入到程序集的XML注释流
    using var xmlStream = currentAssembly.GetManifestResourceStream(embeddedXmlName);
    if (xmlStream != null)
    {
        c.IncludeXmlComments(xmlStream);
    }
});

原理说明 #

EmbedDocumentation会把编译生成的XML注释作为嵌入式资源打包到程序集里，后续通过GetManifestResourceStream可以从程序集中提取这个资源流，Swashbuckle的IncludeXmlComments方法支持直接接收流参数，这样就不需要依赖外部XML文件了。

内容的提问来源于stack exchange，提问作者StuperUser