RB.
RB.

Reputation: 37232

Using dictionary-style data-types in Swagger

Imagine that I have a WebAPI action defined as follows:

[HttpGet]
public string GetFirstValue(KeyValuePair<string, string>[] data)
{
    data = data ?? new KeyValuePair<string, string>[0];

    return data.Any() ? data.ElementAt(0).Value : "No items supplied";
}

I have a model-binder to convert each query-string parameter into an array entry.

You would call it like:

http://localhost/MyController/GetFirstValue?Fruit1=Apple&Fruit2=Banana

The model-binder converts this into an array like [{Fruit1=Apple},{Fruit2=Banana}], and the action returns Apple (as that is the first entry).

I want to document this using Swagger, but the default implementation of Swagger UI will end up generating a URL that puts all the data into multiple query-string parameters called data, which is not how I want to expose my API.

http://localhost:9102/MyController/GetFirstValue?data=Fruit1%3DBanana&data=Fruit2%3DApple

Any ideas? I'm happy to use a different data-type in my action parameter, such as a Dictionary<string, string>, or an IEnumerable or similar - as long as it's an extensible mechanism for providing arbitrary key/values.

Upvotes: 2

Views: 2412

Answers (1)

Ruaidhr&#237; Primrose
Ruaidhr&#237; Primrose

Reputation: 1250

What you're describing isn't possible in Swagger. Referring to the Swagger spec, you need to specify a list of parameters for an operation and each parameter requires a fixed name. There isn't a way to say in Swagger "This operation accepts an arbitrary number of query string parameters with unspecified names".

If you removed the constraint about accepting arbitrary keys then it would be easy, you would just have a "Fruit" parameter of type Array[string] and expect your clients to call http://localhost/MyController/GetFirstValue?Fruit=Apple&Fruit=Banana etc. (Similar to the http://petstore.swagger.io/#!/pet/findPetsByStatus operation for example).

Upvotes: 2

Related Questions