如何在 Swagger 文档页面中包含关于 Controller 类的 XML 注释

Question

我有一个控制器类（不是直接从 ApiController 派生），它有一个 XML 注释：

/// <summary>
/// The controller groups together all methods related to Trial Subscription Management.
/// </summary>
[RoutePrefix("api/v1")]
public class TrialsController : TraceableApiController
{
...
}

我可以在 Swagger 文档页面上看到控制器，但缺少描述控制器的 XML 注释。

是否可以包含描述控制器的注释，如果可以，我该怎么办？

Answer 1

要使控制器级别注释显示在 SwaggerUI 中，您必须向 .AddSwaggerGen() 中的 IncludeXmlComments() 方法添加第二个 bool 参数 = true。像这样：

（为简洁起见，已删除 .AddSwaggerGen()）

            services.AddSwaggerGen(x =>
            {                

                //Locate the XML file being generated by ASP.NET...
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.XML";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);

                //... and tell Swagger to use those XML comments.
                x.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
            });

参考： https://github.com/domaindrivendev/Swashbuckle/issues/1083#issuecomment-530471158