Swashbuckle.AspNetCore IncludeXmlComments 的小更新

JusterZhu

发布于 2025-01-23 20:34:47

1380

文章被收录于专栏：JusterZhuJusterZhu

`Swashbuckle.AspNetCore` `IncludeXmlComments` 的小更新

Intro

最近发现 Swashbuckle.AspNetCore 从 6.7.0 版本开始有个更新简化了 xml 文档注释的处理

Changes

在之前的版本，IncludeXmlComments 需要指定 xml 文档的路径，比如：

{
    option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"), true);
}

我们一般通过在项目项目文件中配置 GenerateDocumentationFile 来生成 xml 文档文件

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

默认地，xml 文档文件的名称就是程序集的名称，新版本新增了一个方法，指定 assembly 即可，无需再指定完整的 xml path 文档，自动使用程序集的名称来指定 xml 文档文件路径，新增方法实现如下：

public static void IncludeXmlComments(
    this SwaggerGenOptions swaggerGenOptions,
    Assembly assembly,
    bool includeControllerXmlComments = false)
{
    swaggerGenOptions.IncludeXmlComments(
        Path.Combine(AppContext.BaseDirectory, $"{assembly.GetName().Name}.xml"),
        includeControllerXmlComments);
}

有了这个方法我们就可以直接指定程序集即可，对于有多个 xml 文档需要引入的时候简化效果就会更加的明显，变化如下：

{
-    option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"), true);
+    option.IncludeXmlComments(Assembly.GetExecutingAssembly(), true);
}