asp.net-web-api - 如何在 Swashbuckle 中包含类和属性描述，使用 OWIN 为 Web Api 2 生成 Swagger 文档？

Question

还没想好，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 先生吗？

Answer 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

IE。

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()); 中指向正确的位置即可。但这是我的选择。