问题描述
更新:我开始怀疑这是否是由于错误:
Update:I'm starting to wonder if this is due to a bug:
https://github.com/domaindrivendev/Swashbuckle/issues/590
但是那里建议的解决方法似乎不能解决我的问题.
But the workaround suggested there does not seem to solve my problem.
我正在使用 Swashbuckle 为 C# ASP.NET Web API 项目生成 API 文档.
I am using Swashbuckle to generate API documentation for a C# ASP.NET Web API project.
我的目标是允许以下作为有效 URL:
My target is to allow the following as valid URL:
/endpoint/items/123/foo?param2=bar
将必需参数 (param1) 设置为foo"，将可选参数 (param2) 设置为bar".我希望两个参数都包含在单个 C# 参数对象中.(带有其他可选参数，如 param3 等).多个端点将使用相同的参数，我希望有一个表示参数的对象.
With a required parameter (param1) set to "foo" and an optional parameter (param2) set to "bar". I would like both parameters contained inside a single C# parameter object. (with other optional parameters like param3 and so on). Several endpoints will use identical parameters and I would like to have a single object representing the parameters.
Swagger/Swashbuckle 的细节大多是一个黑匣子，我无法弄清楚.我在参数列表中得到了重复项.
The details of Swagger/Swashbuckle are mostly a black box to be, and I'm unable to figure this out. I'm getting duplicates in the parameter list.
重现问题的示例代码:
// 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"的重复条目.
With the second method, I receive the parameters inside a single object. But Swagger displays a duplicate entry for the "param1".
截图:Swagger 重复参数
如何让 Swagger/Swashbuckle 不显示param1"的第二个条目?
How can I make Swagger/Swashbuckle not display the second entry for "param1"?
有这种结构的原因是我有多个端点，它们返回不同类型的数据，但它们使用通用参数.某些参数是必需的(以及 ID 的一个 prt)，因此我们希望将这些参数包含在 URL 中，并在查询字符串中包含可选参数.我希望公共参数对象应该包含必需参数和可选参数.
The reason for having this structure is that I have multiple endpoints that return different types of data, but they use common parameters.Some of the parameters are required (and a prt of the ID) so we would like to include those in the URL, with optional parameters in the querystring.I would prefer the common parameter object should include both required and optional parameters.
使用 Visual Studio 2015 更新 1 创建的示例代码.默认 ASP.NET Web API 项目.将上面的代码添加到生成的 ValuesController.cs 中.已安装包 Swashbuckle 5.3.1 + 依赖项.
Sample code created with Visual Studio 2015 update 1. Default ASP.NET Web API project. Adding the code above to the generated ValuesController.cs. Installed package Swashbuckle 5.3.1 + dependencies.
推荐答案
更新:找到了解决方法.好丑:
Update:Found a workaround. It's ugly:
- 在方法中引入显式重复参数.
- 为参数对象中的重复属性添加 JsonIgnore 属性.
然后，Swagger 将为此获取方法参数和文档.ASP.Net 将参数分配给方法参数和参数对象，允许代码使用参数对象.
Swagger will then pick up the method parameter and documentation for this one. ASP.Net will assign parameters to BOTH the method parameter and the parameter object, allowing the code to use the parameter object.
/// <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 在实践中迫使我更改我的(完全工作的)代码以生成文档.
I will not use this approach, it will be too confusing for any other developer reading the code. So unfortunately, Swagger/Swashbuckle has in pratice forced me to change my (fully working) code in order to generate documentation.
除非有人能提出合适的解决方案，否则我认为最好的解决方案是使用简单的方法参数.
Unless anyone can suggest a proper solution I think the best solution is to have plain method parameters.
这篇关于Swagger 中的重复参数输出的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！