Swashbuckle参数说明

Question

我使用SwaggerResponse属性来装饰我的api控制器动作，这一切都很好，但是当我查看生成的文档时，参数的描述字段是空的。

是否存在基于属性的方法来描述操作参数（而不是XML注释）？

Answer 1

使用最新的Swashbuckle，或者更好地说至少我正在使用的Swashbuckle.AspNetCore variant，参数的描述字段现在可以正确显示为输出。

确实需要满足以下条件：

必须启用
• XML comments并使用Swagger配置
• 应使用[FromRoute]，[FromQuery]，[FromBody]或[FromUri]
显式修饰参数
• 方法类型（get / post / put等）相同，应使用[Http...]
进行修饰
• 通常使用<param ...> xml评论
描述参数

完整示例如下所示：

/// <summary>
/// Short, descriptive title of the operation
/// </summary>
/// <remarks>
/// More elaborate description
/// </remarks>
/// <param name="id">Here is the description for ID.</param>
[ProducesResponseType(typeof(Bar), (int)HttpStatusCode.OK)]
[HttpGet, Route("{id}", Name = "GetFoo")]
public async Task<IActionResult> Foo([FromRoute] long id)
{
    var response = new Bar();
    return Ok(response);
}

产生以下输出：

Answer 2

您应该确认您允许Swagger使用XML注释

httpConfig.EnableSwagger(c => {
                if (GetXmlCommentsPath() != null) {
                    c.IncludeXmlComments(GetXmlCommentsPath());
                }
...
...
);

protected static string GetXmlCommentsPath() {
    var path = HostingEnvironment.MapPath("path to your xml doc file");
    return path;
}

您还应该检查是否正在为所需项目生成XML文档。在您想要的项目属性下（Alt + Enter在项目顶部或右键单击 - ＆gt;属性） - ＆gt; 构建 - ＆gt;检查 XML文档文件

Answer 3

为了完整起见，在使用最新版本的psql -v ON_ERROR_STOP=1 和Swashbuckle.AspNetCore (2.1.0)时，在项目的构建中启用Xml文档文件生成

然后对您的Swashbuckle.SwaggerGen/Ui (6.0.0)方法进行以下操作：

ConfigureServices()