如何在 Swashbuckle 生成的带有 OWIN 的 WebApi 2 的 Swagger 文档中包含类和属性描述？答案

【问题标题】：How to include class and property descriptions in Swashbuckle generated Swagger docs for WebApi 2 with OWIN?如何在 Swashbuckle 生成的带有 OWIN 的 WebApi 2 的 Swagger 文档中包含类和属性描述？
【发布时间】：2016-09-19 14:54:37
【问题描述】：

想来想去，this 不一样。

我认为这应该是不言自明的。我想在 Swagger 文档中包含类描述。我的Swagger 配置如下所示：

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "My Api Name");
    c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(GetXmlCommentsPath());

}).EnableSwaggerUi(c => { });

而MyAwesomeController 看起来像这样：

/// <summary>
/// Controller description (is included by Swashbuckle)
/// </summary>
public class MyAwesomeController : ApiController
{
    /// <summary>
    /// Method description (is included by Swashbuckle)
    /// </summary>
    public IHttpActionResult Get()
    {
        return Ok("hello... from the other side");
    }

    public IHttpActionResult Post([FromBody]MyAwesomeModel model)
    {
        return Ok("hello... from the other side");
    }
}

而我的MyAwesomeModel 看起来像这样：

/// <summary>
/// **I would like this to be included in the Swagger description of the parameter**
/// </summary>
public class MyAwesomeModel
{
    /// <summary>
    /// **I would like this to be included in the Swagger description of the parameter**
    /// </summary>
    public string MyProperty { get; set; }
}

如果不雇用 Skeet 先生，这可能吗？

【问题讨论】：

标签： asp.net-web-api owin swagger swashbuckle

【解决方案1】：

嗯...所以也许如果其他人遇到这个。

基本上我找到了一种可以做到这一点的方法，并且我意识到为什么默认情况下没有这样做。不确定这是否是最好的方法，但它就是这样。

在我的解决方案中，POCO 位于与实际 API 分开的项目中，因此，不包括 MyAwesomeModel 的注释描述，因为没有为类和属性生成 XML 节点。因此，在我的 POCO 所在的单独项目中，我修改了属性以生成 XML。

为 POCO 所在的项目生成 XML

确保将 XML 复制到您希望 Swashbuckle 查找它的任何路径。我在项目属性中使用了Post-build event command line；

copy "$(SolutionDir)MyAwesomeProjectWithPocos\bin\MyAwesomeProjectWithPocos.xml" "$(ProjectDir)\bin\MyAwesomeProjectWithPocos.xml"

修改 SwaggerConfig 以包含此 XML

即

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "My Api Name");
    c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(GetXmlCommentsPath());
    c.IncludeXmlComments(GetXmlCommentsPathForModels());

}).EnableSwaggerUi(c => { });

现在，在 Swagger 页面上，如果我从 Model Schema 切换到 Model，我现在可以阅读整个模型和属性说明。

当然，不需要复制 XML 文件，可以在步骤 #3 GetXmlCommentsPathForModels()); 中指向正确的位置，但这是我的选择。

【讨论】：

对我来说，它不会为我的模型上的属性加载<summary>，除非它是像int、bool、string 等原始类型。你遇到这个问题了吗？
老实说不记得了，这是在 2016 年。

【解决方案2】：

如果你已经写了下面的语句

c.IncludeXmlComments(GetXmlCommentsPath());

能否检查xml注释路径方法是否返回了放置Project XML Documentation文件的xml文件的路径？

【讨论】：

XML 文件存在并且生成的默认 cmets 没有问题（控制器和方法文档），但这不是我要求的 - 我还想包含来自用作方法输入参数的类的类定义。我不知道该怎么解释。
最好在他们的 Github 网站上发布您的请求/问题 - github.com/domaindrivendev/Swashbuckle