Swashbuckle参数说明

Question

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

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

Answer 1

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

它确实需要满足以下条件：

• 必须启用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在项目顶部或右键单击 - >属性） - >构建 - >检查XML文档文件

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);
    }
});