Nswag: Web API: Support complex query parameters

Created on 11 May 2016 · 15Comments · Source: RicoSuter/NSwag

public void ActionMethod([FromUri]Point point)
...

should generate the parameters:

point.x
point.y

committed enhancement

Source

RicoSuter

Most helpful comment

Please create a new issue so that we can track this feature...

RicoSuter on 6 Dec 2017

👍3

All 15 comments

This is implemented

RicoSuter on 29 May 2016

@RSuter does NSwag support complex deep objects in the query parameters?

class RequestObject {
public class CommandObjectOne;
public class CommandObjectTwo;
public class CommandObjectThree;
}
Please see "DeepObject" in the spec:
https://swagger.io/docs/specification/serialization/

daniel-gwilt-software on 5 Dec 2017

Is this valid c#?

RicoSuter on 5 Dec 2017

@RSuter I was just using psudo code as an example. Here's some valid C#

```C#
public class MyRequest
{
public OneCommand OneCommand { get; set; }
public TwoCommand TwoCommand { get; set; }
public ThreeCommand ThreeCommand { get; set; }
}

public class OneCommand
{
    public int SomeNumber { get; set; }
    public int AnotherNumber { get; set; }
}

public class TwoCommand
{
    public string SomeName { get; set; }
    public string SomeDescription { get; set; }
}


public class ThreeCommand
{

    public string SomeName { get; set; }
    public string Value { get; set; }
    public string SomeType { get; set; }
}

```

daniel-gwilt-software on 5 Dec 2017

complex-query-parameters-issue

daniel-gwilt-software on 5 Dec 2017

The question is: What do you expect? Swagger cannot express complex query parameters - they must be primitive or otherwise expanded into multiple parameters....

RicoSuter on 5 Dec 2017

Swagger's API shows support for DeepObject:

deepObject | true | n/a | n/a | n/a | /users?id[role]=admin&id[firstName]=Alex
-- | -- | -- | -- | -- | --

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

daniel-gwilt-software on 5 Dec 2017

Ok, maybe this is a Swagger 3.0 feature? Or how would this look like in an actual swagger spec?

RicoSuter on 5 Dec 2017

I don't know if it's Swagger 3.0 or not.

{
  "x-generator": "NSwag v11.12.10.0 (NJsonSchema v9.10.10.0 (Newtonsoft.Json v10.0.0.0))",
  "swagger": "2.0",
  "info": {
    "title": "",
    "version": ""
  },
  "host": "localhost:13953",
  "basePath": "",
  "schemes": [
    "http"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/api/My/Route/{Id}": {
      "get": {
        "tags": [
          "Mine"
        ],
        "operationId": "My_Get",
        "parameters": [
          {
            "type": "string",
            "name": "Id",
            "in": "path",
            "required": true,
            "x-nullable": false
          },
          {
            "type": "object",
            "name": "oneCommand",
            "in": "query",
            "x-schema": {
              "$ref": "#/definitions/OneCommand"
            },
            "x-nullable": true
          },
          {
            "type": "object",
            "name": "twoCommand",
            "in": "query",
            "x-schema": {
              "$ref": "#/definitions/TwoCommand"
            },
            "x-nullable": true
          },
          {
            "type": "object",
            "name": "threeCommand",
            "in": "query",
            "x-schema": {
              "$ref": "#/definitions/ThreeCommand"
            },
            "x-nullable": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "$ref": "#/definitions/MyResponseObj"
            },
            "x-nullable": true
          },
          "500": {
            "description": "",
            "schema": {},
            "x-nullable": true
          }
        }
      }
    },
  "definitions": {
    "OneCommand": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "pageNumber",
        "pageSize"
      ],
      "properties": {
        "someNumber": {
          "type": "integer",
          "format": "int32"
        },
        "anotherNumber ": {
          "type": "integer",
          "format": "int32"
        }
      }
    },
    "TwoCommand": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "someName": {
          "type": "string"
        },
        "someDescription ": {
          "type": "string"
        }
      }
    },
    "ThreeCommand": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "someName": {
          "type": "string"
        },
        "value": {
          "type": "string"
        },
        "someType": {
          "type": "string"
        }
      }
    }
  }
}

daniel-gwilt-software on 5 Dec 2017

Hmm, it does look like this is a 3.0 feature. Do you not support 3.0 yet?

OpenAPI 3.0 supports arrays and objects in operation parameters (path, query, header, and cookie) and lets you specify how these parameters should be serialized. The serialization method is defined by the style and explode keywords:

style defines how multiple values are delimited. Possible styles depend on the parameter location – path, query, header or cookie.
explode (true/false) specifies whether arrays and objects should generate separate parameters for each array item or object property.
OpenAPI serialization rules are based on a subset of URI template patterns defined by RFC 6570. Tool implementers can use existing URI template libraries to handle the serialization, as explained below.

I'd imagine that NSwag would detect a complex object and automatically set the "style" to "DeepObject" if the parameter is "[FromQuery]". Although, I'm not sure as I'm very new to these tools.

daniel-gwilt-software on 5 Dec 2017

I just noticed this