visual-studio - 如何在 Swagger 文档页面中包含 Controller 类的 XML 注释

Question

我有一个具有 XML 注释的 Controller 类(不直接从 ApiController 派生):

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

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

是否可以包含描述 Controller 的注释，如果可以，我必须做什么？

Answer 1

要让 Controller 级别的注释显示在 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