如何基于ABP框架为各API版本添加Swagger XML注释？

我之前也碰到过一模一样的情况——在应用层API里加了/// <summary>注释，但Swagger UI就是不显示，折腾了好一阵才找到完整的解决方案，给你梳理几个关键步骤：

1. 先确保项目生成XML注释文件 #

ABP基于ASP.NET Core，所以第一步和普通Swagger配置一样，得让你的应用层API项目编译时生成XML注释文件。打开你的应用层API项目的.csproj文件，添加以下配置：

<PropertyGroup>
  <!-- 启用XML注释生成 -->
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <!-- 忽略"缺少XML注释"的编译警告，避免满屏警告 -->
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

如果需要指定XML文件的输出路径（比如发布模式下怕路径不对），可以再加一行：

<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\YourAppApiProjectName.xml</DocumentationFile>

记得把YourAppApiProjectName替换成你实际的项目名称。

2. 在ABP模块中配置Swagger读取XML注释 #

ABP的Swagger配置是在模块类（继承AbpModule的类，一般是Web层或Api层的模块）里做的。找到模块的ConfigureServices方法，在AddAbpSwaggerGen的配置里添加XML注释的路径：

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var configuration = context.Services.GetConfiguration();

    // 其他配置代码...

    context.Services.AddAbpSwaggerGen(options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
        options.DocInclusionPredicate((docName, description) => true);
        options.CustomSchemaIds(type => type.FullName);

        // 核心：添加应用层API的XML注释文件
        var apiXmlPath = Path.Combine(AppContext.BaseDirectory, "YourAppApiProjectName.xml");
        // includeControllerXmlComments设为true，才能显示控制器和方法的注释
        options.IncludeXmlComments(apiXmlPath, includeControllerXmlComments: true);

        // 如果你的Application Service层也写了注释，并且是通过ABP动态API暴露的，也要加对应的XML文件
        // var appServiceXmlPath = Path.Combine(AppContext.BaseDirectory, "YourAppServiceProjectName.xml");
        // options.IncludeXmlComments(appServiceXmlPath);
    });
}

这里要注意：如果你的API是ABP自动生成的动态API（比如把Application Service直接暴露为Web API），一定要把Application Service项目的XML注释文件也加进来，不然动态API的注释还是不会显示。

3. 确认Swagger UI中间件配置正确 #

最后检查模块的OnApplicationInitialization方法，确保正确启用了Swagger和Swagger UI：

public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
    var app = context.GetApplicationBuilder();
    var env = context.GetEnvironment();

    // 其他中间件（比如静态文件、认证授权等）...

    if (env.IsDevelopment())
    {
        app.UseSwagger();
        app.UseSwaggerUI(options =>
        {
            options.SwaggerEndpoint("/swagger/v1/swagger.json", "你的API V1");
        });
    }
}

几个容易踩的坑 #

• 注释格式错误：必须用/// <summary>...</summary>这种XML注释格式，//或者/* */是不会被Swagger识别的，而且注释要直接放在方法、参数或者类的上方。
• XML文件路径不对：编译后可以去项目的输出目录（比如bin/Debug/net6.0）看看XML文件有没有生成，路径是否和代码里写的一致。
• 动态API的注释遗漏：如果用了ABP的动态API，一定要把Application Service项目的XML文件也加到Swagger配置里，不然自动生成的API接口不会显示注释。

按这些步骤操作后，重新编译运行项目，Swagger UI里应该就能看到你加的注释了！

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