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

Question

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

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

第2步：创建Web API项目

第3步：安装Swashbuckle 5.6.0 NuGet包

Step4：启用生成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 文档。

Answer 3

尝试做

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

Answer 4

对于 .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));
});

Answer 5

就我而言，评论没有出现，因为我在评论中添加了网址。不知道为什么它会破坏它，但一旦我删除了网址，一切就都正常了。

Answer 6

请勿在评论中包含任何“&”符号。如果这样做，您的文档将不会显示。

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);
        });

Answer 8

在 .net6 core 的 swagger 页面 UI 中获取控制器的 XML 注释时，我也遇到了这个问题。我通过在项目属性中启用“XML 文档文件路径”选项找到了一个简单的解决方案。您可以按照以下提到的简单步骤操作：

• 右键单击项目并打开属性。
• 转到构建 -> 输出 -> 启用“文档文件”。 （此外，您可以设置 XML 文档文件的路径，否则将使用默认位置）