如何在Swagger文档页面中包含控制器类的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注释。

是否可以包含描述控制器的注释，如果可以，我需要做什么？

- Captain Sensible

---

在回答后立即意识到您想要控制器注释。我自己也注意到了这一点，但我也没有解决方案。 - Padraic

这个控制器的XML文档说明是否缺失？你调用了IncludeXMLComments吗？ - jps

评论（总结，备注）对于在控制器内定义的方法工作得很好。但是与控制器类本身相关的XML注释永远不会显示在生成的Swagger文档中。 - Captain Sensible

你有解决这个问题的办法吗？ - Chaos Crafter

Answer 1

为了让控制器级别的注释在SwaggerUI中显示，您需要向.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

- Coy Meeks

Answer 2

我假设你正在使用 Swashbuckle 生成 Swagger 文档。目前，Swashbuckle 并没有这个功能。在撰写本文时，该功能正在开发中。

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

- Padraic