是否有添加Swagger注释的替代方案？如何同步Manager类注释至Swagger UI

核心思路 #

无需手动复制粘贴注释，通过读取Manager类生成的XML注释文档，在Swagger文档生成阶段自动替换对应控制器方法的注释内容。

具体实现步骤 #

1. 开启XML注释生成 #

分别在Manager类所在项目和Web控制器项目的属性设置中，勾选「生成XML文档文件」，记录好两个XML文件的输出路径（示例：bin\Debug\net6.0\YourManagerProject.xml、bin\Debug\net6.0\YourWebProject.xml）。

2. 自定义Swagger注释过滤器 #

创建一个实现IDocumentFilter接口的过滤器类，负责读取Manager的XML注释并替换控制器方法的Swagger注释：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Xml.Linq;

public class ManagerCommentDocumentFilter : IDocumentFilter
{
    private readonly XDocument _managerXmlDoc;

    public ManagerCommentDocumentFilter(string managerXmlPath)
    {
        _managerXmlDoc = XDocument.Load(managerXmlPath);
    }

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var apiDescription in context.ApiDescriptions)
        {
            // 匹配控制器方法对应的Manager方法（需根据你的代码结构调整映射逻辑）
            var targetManagerMethod = GetMatchedManagerMethod(apiDescription);
            if (string.IsNullOrEmpty(targetManagerMethod)) continue;

            // 从Manager的XML文档中提取方法注释
            var methodComment = FetchManagerMethodComment(targetManagerMethod);
            if (!string.IsNullOrEmpty(methodComment))
            {
                // 替换Swagger中当前接口的注释
                var operation = swaggerDoc.Paths[apiDescription.RelativePath].Operations[apiDescription.HttpMethod];
                operation.Summary = methodComment;
                // 如需替换描述字段，可赋值operation.Description
            }
        }
    }

    // 这里需要根据你的业务逻辑，建立控制器方法与Manager方法的映射
    private string GetMatchedManagerMethod(ApiDescription apiDescription)
    {
        // 示例：假设控制器方法名与Manager方法名完全一致
        return apiDescription.ActionDescriptor.RouteValues["action"];
    }

    private string FetchManagerMethodComment(string methodName)
    {
        // 从XML文档中查找对应Manager方法的summary注释
        var methodElement = _managerXmlDoc.Descendants("member")
            .FirstOrDefault(m => m.Attribute("name")?.Value.StartsWith($"M:YourNamespace.Manager.{methodName}") == true);
        return methodElement?.Element("summary")?.Value.Trim();
    }
}

3. 注册过滤器到Swagger服务 #

在Program.cs的Swagger配置中，加载两个XML文件并注册自定义过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // 加载Web项目自身的XML注释
    var webXmlPath = Path.Combine(AppContext.BaseDirectory, "YourWebProject.xml");
    c.IncludeXmlComments(webXmlPath);

    // 加载Manager项目的XML注释，并注册自定义过滤器
    var managerXmlPath = Path.Combine(AppContext.BaseDirectory, "YourManagerProject.xml");
    c.DocumentFilter<ManagerCommentDocumentFilter>(managerXmlPath);
});

注意事项 #

• 方法匹配逻辑需根据实际代码结构调整，比如控制器与Manager方法名不同时，要建立准确的映射规则
• 若Manager方法存在重载，需通过参数类型进一步匹配对应的XML注释
• 确保XML文件在发布时能复制到输出目录，可在项目文件中添加配置：<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>

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