XML注释在Swagger文档中未显示，这是Swagger的错误吗？

Question

Swagger的xml注释在文档UI中未显示，不确定我是否遗漏了什么..至少有人指导我这是一个bug。

步骤1：创建一个全新的ASP.NET Web API项目。

步骤2：创建了一个Web API项目。

步骤3：安装了Swashbuckle 5.6.0 NuGet包。

步骤4：启用生成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);
     });
}

步骤6：向控制器添加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没有显示注释，我不确定我在哪里出错了：

- ram4sof

---

在xmlPath变量处设置一个断点，检查路径是否正确。 - CodeNotFound

XML路径正确，我确实看到了在bin文件夹中创建的带有注释的XML文件。 - ram4sof

在第一步中，您正在创建ASP.NET Core项目，但是当您将Swashbuckle包添加到ASP.NET Web API时，SwaggerConfig.cs会被创建。如果您正在使用Core，请使用Swashbuckle.AspNetCore包。 - Yehor Androsov

@YegorAndrosov，你找到解决方案了吗？ - Guilherme Waltricke

@GuilhermeWaltricke OP的问题是因为他们使用了ASP.NET包而不是Core。 - Yehor Androsov

Answer 1

< p >对于 .NET 6，请确保配置您的 < code > program.cs

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

然后在您的.csproj文件中添加属性组。

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

- Edward Garcia

---

非常好，谢谢。 - hamaronooo

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 文档。

- HyperQuantum

Answer 3

对于.NET 6，基于Microsoft文档，另一种实现方式如下：

打开项目文件 .csproj 并添加以下行：

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

然后在程序文件中更改以下内容：

  builder.Services.AddSwaggerGen();

对于这个问题

builder.Services.AddSwaggerGen(options =>
{
    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

- Okyam

Answer 4

尝试做以下操作

1. 移除旧版本
2. 在“解决方案资源管理器”中，右键单击项目并选择“编辑 <project_name>.csproj”。
3. 手动将突出显示的行添加到.csproj文件中

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

4. 生成新文件

https://learn.microsoft.com/en-us/samples/aspnet/aspnetcore.docs/getstarted-swashbuckle-aspnetcore/?tabs=visual-studio

- kawtog

Answer 5

在我的情况下，注释没有出现是因为我在备注中放了一个URL。不确定为什么会破坏它，但一旦我删除了URL，一切都正常了。

- hooah

---

你提供了我需要的提示。在我的情况下，我在备注中包含了一个“&”符号，即<remarks>... & ...</remarks>，结果所有我辛勤编写的文档都变得不可见了。 - CAK2

Answer 6

在您的注释中不要包含任何&符号。如果您这样做，您的文档将无法显示。

- CAK2

Answer 7

在我的案例中，我始终将生成的 XML 复制设置为构建选项。

并且在 AddSwaggerGen 选项的启动时，我添加了一些代码，如果文件存在，则通过 IncludeXmlComments 生成注释：

        services.AddSwaggerGen((opt) =>
        {
            opt.SwaggerDoc("v1", new OpenApiInfo { Title = "API", Version = "v1",
                Description = "Your app desc",
                Contact = new OpenApiContact()
                {
                    Name = "@yourname",
                    Url = new System.Uri("yoursite.com"),
                }
            });

            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);

            if (File.Exists(xmlPath))
                opt.IncludeXmlComments(xmlPath);
        });

- toha