Swagger文档中没有显示XML注释，这是swagger中的错误吗？

Question

Swagger xml 注释没有显示在文档 UI 中，不确定我在这里遗漏了一些东西..至少有人告诉我这是一个错误

Step1：创建一个全新的 ASP.NET Web 应用程序 Web API 项目

Step2：创建Web API项目

步骤3：安装Swashbuckle 5.6.0 NuGet包

第四步：启用生成 XML 文档文件（项目属性 -> 构建）

步骤 5：更新 SwaggerConfig.cs 以包含 XmlComments

public static void Register()
{
    var thisAssembly = typeof(SwaggerConfig).Assembly;

    GlobalConfiguration.Configuration.EnableSwagger(c =>
    {
                var xmlFile = "bin\\" + $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
     });
}

Step6：向控制器添加XML注释

///<Summary>
/// Get these comments1
///</Summary>
public class ValuesController : ApiController
{
    ///<Summary>
    /// Get these comments2
    ///</Summary>
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
}

WebApplication1.xml 也在 bin 文件夹中生成

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>WebApplication1</name>
    </assembly>
    <members>
        <member name="T:WebApplication1.Controllers.ValuesController">
            <Summary>
             Get these comments1
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Get">
            <Summary>
             Get these comments2
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Get(System.Int32)">
            <Summary>
             Get these comments3
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Post(System.String)">
            <Summary>
             Get these comments4
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Put(System.Int32,System.String)">
            <Summary>
             Get these comments5
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Delete(System.Int32)">
            <Summary>
             Get these comments6
            </Summary>
        </member>
    </members>
</doc>

但是 Swagger UI 没有显示评论，我不确定我在哪里出错了：

Answer 1

对于 .NET 6，请确保配置您的program.cs

builder.Services.AddSwaggerGen(c =>
{
  c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, 
  $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
});

然后在 .csproj 中添加属性组

  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

Answer 2

就我而言，Swagger 中缺少 XML 注释，因为 API 本身和模型类位于不同的程序集中。

我是这样解决的：

public void ConfigureServices(IServiceCollection services)
{
    // ...

    services.AddSwaggerGen(c =>
    {
        // ...other stuff

        // include API xml documentation
        var apiAssembly = typeof(SomeApiClass).Assembly;
        c.IncludeXmlComments(GetXmlDocumentationFileFor(apiAssembly));

        // include models xml documentation
        var modelsAssembly = typeof(ModelsProject.SomeModelClass).Assembly;
        c.IncludeXmlComments(GetXmlDocumentationFileFor(modelsAssembly));
    });
}

private static string GetXmlDocumentationFileFor(Assembly assembly)
{
    var documentationFile = $"{assembly.GetName().Name}.xml";
    var path = Path.Combine(AppContext.BaseDirectory, documentationFile);

    return path;
}

当然，不要忘记在这两个.csproj文件中也启用 XML 文档。