Swagger中的参数输出重复

Question

更新:我开始怀疑这是否是由于一个错误:

https://github.com/domaindrivendev/Swashbuckle/issues/590

但是解决方法表明似乎没有解决我的问题.

---

我正在使用Swashbuckle为C#ASP.NET Web API项目生成API文档.

我的目标是允许以下作为有效的URL:

/endpoint/items/123/foo?param2=bar

将所需参数(param1)设置为"foo",将可选参数(param2)设置为"bar".我希望两个参数都包含在一个C#参数对象中.(使用其他可选参数,如param3等).几个端点将使用相同的参数,我希望有一个表示参数的对象.

Swagger/Swashbuckle的细节大多是黑盒子,我无法弄明白.我在参数列表中得到了重复项.

重现问题的示例代码:

    // This endpoint is generating documentation the way I would like.
    [HttpGet]
    [Route("endpoint1/items/{id}/{param1}")]
    public string GetDataForParameters(int id, string param1, string param2 = null, string param3 = null)
    {
        return string.Format("Params: {1}, {2}, {3}", id, param1, param2, param3);
    }

    // This endpoint has the structure I would like, but I get duplicates for param1 in the documentation.
    [HttpGet]
    [Route("endpoint2/items/{id}/{param1}")]
    public string GetDataForParameters(int id, [FromUri(Name = "")]MyParams myParams)
    {
        return string.Format("Params: {1}, {2}, {3}", id, myParams.Param1, myParams.Param2, myParams.Param3);
    }

    public class MyParams
    {
        public string Param1 { get; set;}
        public string Param2 { get; set;}
        public string Param3 { get; set;}
    }

使用第二种方法,我在单个对象中接收参数.但Swagger显示"param1"的重复条目.

屏幕截图:Swagger重复参数

如何让Swagger/Swashbuckle不显示"param1"的第二个条目？

---

拥有此结构的原因是我有多个端点返回不同类型的数据,但它们使用通用参数.某些参数是必需的(以及ID的prt),因此我们希望在URL中包含这些参数,并在查询字符串中包含可选参数.我更喜欢通用参数对象应包括必需参数和可选参数.

使用Visual Studio 2015更新创建的示例代码1.默认的ASP.NET Web API项目.将上面的代码添加到生成的ValuesController.cs中.安装包Swashbuckle 5.3.1 +依赖项.

Answer 1

更新：找到了解决方法。它很丑：

1. 在方法中引入显式重复参数。
2. 将 JsonIgnore 属性添加到参数对象中的重复属性。

然后 Swagger 将获取该方法的参数和文档。ASP.Net 会将参数分配给方法参数和参数对象，从而允许代码使用参数对象。

    /// <param name="param1">URL parameters must be documented on this level.</param>
    [HttpGet]
    [Route("endpoint2/items/{id}/{param1}")]
    public string GetDataForParameters(int id, string param1, [FromUri(Name = "")]MyParams myParams)
    {
        // the param1 method parameter is a dummy, and not used anywhere.
        return string.Format("Params: {1}, {2}, {3}", id, myParams.Param1, myParams.Param2, myParams.Param3);
    }

    public class MyParams
    {
        /// <summary>
        /// Cannot add documentation here, it will be ignored.
        /// </summary>
        [JsonIgnore]
        public string Param1 { get; set;}
        /// <summary>
        /// This is included. Querystring parameters can be documented in this class.
        /// </summary>
        public string Param2 { get; set;}
        public string Param3 { get; set;}
    }

我不会使用这种方法，对于任何其他阅读代码的开发人员来说都太混乱了。不幸的是，Swagger/Swashbuckle 实际上迫使我更​​改我的（完全工作的）代码以生成文档。

除非有人能提出正确的解决方案，否则我认为最好的解决方案是使用简单的方法参数。