如何在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

我假设您正在使用Swashbuckle来生成Swagger文档。目前这在Swashbuckle中不是一个功能。在撰写本文时，它正在进行中。

https://github.com/domaindrivendev/Swashbuckle/pull/1087

Answer 2

要使控制器级别的注释显示在SwaggerUI中，必须在.AddSwaggerGen（）中的IncludeXmlComments（）方法中添加第二个布尔参数= 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