GET requests that use complex objects

[replaysMike]

Hey all,

I can't seem to find a proper solution to dealing with GET requests that use a complex request object rather than individual method calls. Swashbuckle seems to do some flattening of the query parameters already but it prepends the variable name specified in the GET request. For some reason, it also generates a definition for the complex request object but doesn't use it - which leads to swagger warnings. I did find one other issue which seems to be referencing the same: #70 and domaindrivendev/Swashbuckle.AspNetCore#66 but I could not find anything in the 5.0 documentation that would lead me to believe this is already handled within Swashbuckle.

Example method:

When using:

[HttpGet]
public async Task<IHttpActionResult> GetThings(GetThingsRequest queryParameters) {}

instead of:

[HttpGet]
public async Task<IHttpActionResult> GetThings(int[] ids, string name, int pageNumber) {}

results in schema:

paths: {
    "/api/things": {
      "get": {
        "summary": "Get some things",
        "operationId": "getThings",
        "parameters": [
          {
            "name": "queryParameters.ids",
            "in": "query",
            "description": "The ids to reference",
          }
    }
}
...
definitions: {
    "GetThingsRequest": {
      "type": "object",
      "properties": {
        "ids": {
          "description": "The list of id's to filter by",
          "type": "array",
          "items": {
            "format": "int32",
            "type": "integer"
          }
        },
        "name": {
          "format": "date-time",
          "description": "The date to filter by",
          "type": "string"
        },
    }
}
...

But really instead of "queryParameters.ids" it should be defining just "ids" as the parameter. Is there a way to do this without invoking a custom OperationFilter?

[replaysMike]

domaindrivendev/Swashbuckle.AspNetCore#66 seems to reference that using the [FromUri] attribute on a property will work, but under .Net Web API 2 that attribute can only be applied to Class and Parameters as per https://msdn.microsoft.com/en-us/library/system.web.http.fromuriattribute(v=vs.118).aspx

Maybe this is specific to .Net core? (yes, yes it is).

[replaysMike]

For reference, the following IOperationFilter will perform this desired behavior - I'm hoping this isn't needed. Alternatively, it would be even better I suppose to point a $ref to the input request object being used (it's in the schema) but I didn't tackle this part.

public class ComplexRequestObjectOperationFilter : IOperationFilter
    {
        public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
        {
            var actionDescriptor = apiDescription.ActionDescriptor;
            var method = apiDescription.HttpMethod.Method.ToLower();
            var controllerName = actionDescriptor.ControllerDescriptor.ControllerName;
            var parameterBindings = actionDescriptor.ActionBinding.ParameterBindings;
            // we are only interested in modifying GET requests
            if (method == "get")
            {
                if (parameterBindings.Length > 0)
                {
                    var parameterDescriptor = actionDescriptor.ActionBinding.ParameterBindings.First().Descriptor;
                    var parameterName = parameterDescriptor.ParameterName;
                    // correct the name of the property to _not_ prepend it with the controller method's argument name
                    if (parameterDescriptor.ParameterType.BaseType == typeof(object))
                    {
                        foreach (var property in operation.parameters)
                            property.name = property.name.Replace(parameterName + ".", "");
                    }
                }
            }
        }
    }

[bobvandevijver]

I have the same issue: even though requests do work correctly with the extra queryParameters part, it should not be there according to the spec.

I'm now using the snippet above, which works like a charm.

[heldersepu]

@bobvandevijver Sorry but that link is not a spec document by any means
https://docs.microsoft.com/en-us/aspnet/web-api/overview/formats-and-model-binding/parameter-binding-in-aspnet-web-api#using-fromuri

I actually do prefer the extra queryParameters that way if you have multiple object in the url you can clearly identify them, like this one:
http://swashbuckletest.azurewebsites.net/swagger/ui/index?filter=Fr#/FromUri/FromUri_GetWith0

[bobvandevijver]

The link contains the MS docs about what the code should do: so yes, it is not a spec in literal sense, but is does describe how it is supposed to work.

When you have multiple objects in your controller parameters, the queryParameters part is actually required. However, if you require multiple objects in your requests, you're probably doing something wrong as such objects need to be tailored to your API anyways. If I understand your example correctly (the v1 and v2 are used to indicate API versions), it is actually wrong: that distinction should be on URL level.

Conclusion: for single object arguments the queryParameters should be left out, for multiple objects it should be there (but I would not recommend using it).

[heldersepu]

@bobvandevijver
On my example v1& v2 are abbreviations for value1 and value2, nothing to do with API versioning.

I agree with you, for single object arguments the queryParameters should be left out.
The key is "should", It is not a requirement.

[daniel-gwilt-software]

This is indeed more than just a styling issue. Query string serializers don't expect the extra queryParameters text to be there. This prevents the usage of 3rd party tools, like NSwagStudio, for code generation. Spent a whole day figuring this out.

[heldersepu]

@daniel-gwilt-software sounds like you should fill a bug report with NSwagStudio

[daniel-gwilt-software]

@heldersepu NSwagStudio does support creating C# from the JSON instead of the controllers, so this is what we'll use. It's really all the confusion created by not following the standard conventions that were upsetting. I believe that's what standards are for. To facilitate communication on intention. It also creates more work for developers to use tools that don't follow popular conventions. For example, I had to write a custom object to query string conversion function to hit the API instead of being able to use the built-in AngularJS and/or JQuery functions. (https://docs.angularjs.org/api/ng/service/$httpParamSerializer)

[heldersepu]

@daniel-gwilt-software Who is not following the standard conventions ?

[daniel-gwilt-software]

@heldersepu It turns out support for Complex Objects in the query string are supported in the Swagger 3.0 spec, but Swashbuckle nor NSwag support 3.0 right now. Thanks for your help.

https://swagger.io/docs/specification/serialization/

[tihomir-kit]

Hi. I assume no updates on this perhaps?

[kiranakhale]

public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters != null)
{
foreach (Parameter param in operation.parameters.Where(p => p.name.Contains('.')))
{
param.name = param.name.SplitWithoutEmpty('.').Last();
}
}
}