Duplicate parameter output in Swagger

Question

Update: I'm starting to wonder if this is due to an error:

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

But the suggested workaround does not seem to solve my problem.

---

I am using Swashbuckle to create API documentation for a C # ASP.NET Web API project.

My goal is to allow the following as a valid URL:

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

With the required parameter (param1) set to "foo" and the optional parameter (param2) set to "bar". I would like both parameters to be contained within the same C # parameter object. (with other optional parameters like param3 etc.). Several endpoints will use the same parameters, and I would like to have one object representing the parameters.

Details Swagger / Swashbuckle is basically a black box, and I can't figure it out. I get duplicates in the parameter list.

Sample code to reproduce the problem:

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

The second method, I get the parameters inside the same object. But Swagger displays a double entry for "param1".

Screenshot: Duplicate Swagger option

How can I make Swagger / Swashbuckle not display the second entry for "param1"?

---

The reason for having this structure is because I have several endpoints that return different data types, but they use common parameters. Some parameters are required (and prt identifier), so we would like to include them in the URL, with optional parameters in the query string. I would prefer the generic parameter object to include both required and optional parameters.

Sample Code Created Using Visual Studio 2015 Update 1. ASP.NET default web API project. Adding the code above to the generated ValuesController.cs. Installed Swashbuckle 5.3.1 package + dependencies.

Answer 1

Update: A workaround was found. This is ugly:

• Insert an explicit duplicate parameter into the method.
• Add the JsonIgnore attribute for the repeating properties of the parameter object.

Then Swagger will take the method parameter and documentation for this. ASP.Net will assign BOTH parameters to the method parameter and 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;} } 

I will not use this approach, it will be too confusing for any other developer reading the code. So, unfortunately, Swagger / Swashbuckle has the right to force me to change my (fully working) code to generate documentation.

If anyone can suggest the right solution, I think the best solution is to have simple method parameters.

Answer 2

When Swashbuckle creates the swagger.json file, it looks at the routing and query parameters. Therefore, when you use Get(string param1, string param2 ..) , which automatically tells Swashbuckle that these parameters are necessary (because they are NOT set to = null )

When using Get([FromUri(Name = "")]MyParams myParams) Swashbuckle looks for data annotations (System.ComponentModel.DataAnnotes) in your model to indicate whether a parameter is needed or not.

Set parameter Param1

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