Swashbuckle 参数说明

Question

我正在使用 SwaggerResponse 属性来装饰我的 api 控制器操作，这一切工作正常，但是当我查看生成的文档时，参数的描述字段为空。

是否有基于属性的方法来描述动作参数（而不是 XML 评论）？

Answer 1

您应该确认您允许 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 文档。在您想要的项目下 Properties（在项目顶部按 Alt + Enter 或右键单击 -> 属性）-> Build -> 检查 XML 文档文件

Answer 2

使用最新的 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 3

为了完整起见，当使用最新版本的 Swashbuckle.AspNetCore (2.1.0) 和 Swashbuckle.SwaggerGen/Ui (6.0.0) 时，请在项目的 Build

中启用 Xml 文档文件生成

然后是您的 ConfigureServices() 方法：

services.ConfigureSwaggerGen(options =>
{
    options.SingleApiVersion(new Info
    {
        Version = "v1",
        Title = "My API",
        Description = "API Description"
    });
    options.DescribeAllEnumsAsStrings();

    var xmlDocFile = Path.Combine(AppContext.BaseDirectory, $"{_hostingEnv.ApplicationName}.xml");
    if (File.Exists(xmlDocFile))
    {
        var comments = new XPathDocument(xmlDocFile);
        options.OperationFilter<XmlCommentsOperationFilter>(comments);
        options.ModelFilter<XmlCommentsModelFilter>(comments);
    }
});

Swashbuckle 参数说明

Swashbuckle parameter descriptions

c#

swagger

swashbuckle