Is it possible to support dynamic query parameters with Swagger?

[Aqua]

When trying to use Swagger I would like to support dynamic query parameter names. Is this something that is possible? I tried leaving the name attribute off of the ApiImplicitParam operations but then it appears Swagger uses the dataType attribute to set the parameter name.

[Ron]

I'm not sure how that'll work in terms of describing the API - "we also support a random set of characters as a parameter name that'll mean something."?

Can you maybe share an example for this use case?

On Sat, Mar 1, 2014 at 11:37 PM, Aqua <chris....@gmail.com> wrote:

When trying to use Swagger I would like to support dynamic query parameter names. Is this something that is possible? I tried leaving the name attribute off of the ApiImplicitParam operations but then it appears Swagger uses the dataType attribute to set the parameter name.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Chris Omland]

Sure. Say you have a resource in your api call it an 'Object'. Then your application lets users define there own fields on that object, you don't know what those field names or values will be but you need to be able to support returning objects that are filtered by field name and value. 

So you might have something like:

GET /foobar.com/api/object

GET /foobar.com/api/object?field1=val1&field2=val2

But field1 and field2 are defined by the user, you don't know their true names or values.

Does that help?

-Chris

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Ron]

I understand what you're saying. At the moment (and Tony may correct me), Swagger does not support this form of API specification.

Just as a clarification, two questions:

1. In your example, you write GET /foobar.com/api/object?field1=val1&field2=val2 - but I don't understand the field values in this case. Since this is a GET operation and you want to filter the fields, you'd only need the field names. In that case, I'd expect the API to look like GET /foobar.com/api/object?fields=fieldName1,fieldName2,fieldName3 (This can be described by Swagger, btw).
   
2. I assume that in this case, there are no additional fields that can be sent, otherwise how can you tell in the back-end which fields are yours and which are the user's?

[tony tam]

Ron is correct--the goal of swagger is to help consumers understand what a service supports, by being explicit and declarative about the input parameters.  Your service can of course consume anything that you send to it, but without being clear about what keys are supported, how would anyone ever know that you can/should send "foo=bar"?

On Monday, March 3, 2014 5:13:59 AM UTC-8, Ron R wrote:

I understand what you're saying. At the moment (and Tony may correct me), Swagger does not support this form of API specification.

Just as a clarification, two questions:

1. In your example, you write GET /foobar.com/api/object?field1=val1&field2=val2 - but I don't understand the field values in this case. Since this is a GET operation and you want to filter the fields, you'd only need the field names. In that case, I'd expect the API to look like GET /foobar.com/api/object?fields=fieldName1,fieldName2,fieldName3 (This can be described by Swagger, btw).
   
2. I assume that in this case, there are no additional fields that can be sent, otherwise how can you tell in the back-end which fields are yours and which are the user's?

On Mon, Mar 3, 2014 at 6:00 AM, Chris Omland <chris....@gmail.com> wrote:

Sure. Say you have a resource in your api call it an 'Object'. Then your application lets users define there own fields on that object, you don't know what those field names or values will be but you need to be able to support returning objects that are filtered by field name and value. 

So you might have something like:

GET /foobar.com/api/object

GET /foobar.com/api/object?field1=val1&field2=val2

But field1 and field2 are defined by the user, you don't know their true names or values.

Does that help?

-Chris

On Sun, Mar 2, 2014 at 7:04 AM, Ron <web...@gmail.com> wrote:

I'm not sure how that'll work in terms of describing the API - "we also support a random set of characters as a parameter name that'll mean something."?

Can you maybe share an example for this use case?

On Sat, Mar 1, 2014 at 11:37 PM, Aqua <chris....@gmail.com> wrote:

When trying to use Swagger I would like to support dynamic query parameter names. Is this something that is possible? I tried leaving the name attribute off of the ApiImplicitParam operations but then it appears Swagger uses the dataType attribute to set the parameter name.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Chris Omland]

The user would know the valid fields and values because they define them in the application. So basically lets say you have a product object and the application allows you to extend that product object to contain your own custom fields. The user might define two custom fields for products, 'productColor' and 'productWarrantyId'. Now the user can create multiple products in the system and set the productColor and productWarrantyId for each of those products. Now if the user wants to find all red products with warrantyId=1234 they would request:

GET /foobar.com/api/products?productColor=Red&productWarrantyId=1234

Further more the application lets multiple values live in a single field, so a product might have two colors red and green. You then would request:

GET /foobar.com/api/products?productColor=Red&productColor=Green

Hopefully that helps. It's not uncommon to see applications that allow users to extend the data model creating their own fields.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Ron]

Chris,

That answers one of my question, but not the one regarding additional 'fixed' fields. I'm just not sure how you'd deal with overlapping field names (that is, the user's and yours).

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Chris Omland]

I think there are multiple ways to handle that, and it kind of depends on your application and how you chose to implement it. For me the users is only ever filtering on their own user defined fields so I don't have to worry about the query parameters overlapping. 

[Ron]

Okay, here's the solution I'd suggest.

I believe that telling the user "and here you can put some dynamic parameter fields and you should know which they are since you wrote them" is not really helpful.

Now, remember that Swagger is in fact a specification of what the API description should look like. There's nothing stopping you from generating it dynamically (as most libraries do) - so in that case, you can actually generate the API Description dynamically and present the user with their own relevant fields and their types.

The challenge may be with the field types, but I believe that you should be able to support most of your use cases, and in the worst case say that a field is a string and do additional manipulations as required on your end.

Does that make sense to you?

[Chris Omland]

I think it does but will have to spend some time with it. I had this same thought but wasn't exactly sure how to implement it. I'm using play2 and I wasn't sure if I could generate the annotations dynamically at run-time based on what the user defined fields are. If I can generate these annotations at runtime I think this would be a viable solution.

[Chris Omland]

To be clear, I am using the play2-java module.

[tony tam]

chris, take a look here:

https://github.com/wordnik/swagger-core/blob/master/samples/java-play2/app/controllers/PetApiController.java#L78

You can add as many parameters as you like, and swagger will introspect them and turn them into operation parameters in the json (and therefore ui)

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Chris Omland]

Thanks for the link. I think the challenge for me is I don't know what the parameters are until runtime and I don't think I can generate the java annotations at runtime. So still not exactly sure how I will accomplish supporting dynamic parameter names.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Kjetil Matheussen]

Hi,

Since you are using play2, you can use this system
to generate the swagger json: https://github.com/sun-opsys/api-doc

Example:

object ApiDoc extends Controller{

val docs = List(
"""
GET /api/v1/users/

DESCRIPTION
Get user

PARAMETERS
id: String(query) <- The user id

ERRORS
400 User not found
400 Syntax Error
""")


def get() = Action { request =>
Ok(SwaggerUtil.getMain("/api/v1/", docs))
}
def getPath(path: String) = Action { request =>
Ok(SwaggerUtil.getJson("/api/v1/", docs, "users"))
controller.getPath(path)
}
}

This way, you can change the name of the query variable
during runtime by manipulating the "docs" string.
Translating the above to java should be trivial.

This system is a work in quite early progress, though.

>>>>>>>>>>>>> it, send an email to swagger-swaggers...@googlegroups.com.

>>>>>>>>>>>>>
>>>>>>>>>>>>> For more options, visit
>>>>>>>>>>>>> https://groups.google.com/groups/opt_out.
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>> --
>>>>>>>>>>>> You received this message because you are subscribed to a topic
>>>>>>>>>>>> in the Google Groups "Swagger" group.
>>>>>>>>>>>> To unsubscribe from this topic, visit
>>>>>>>>>>>> https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.
>>>>>>>>>>>> To unsubscribe from this group and all its topics, send an email
>>>>>>>>>>>> to swagger-swaggers...@googlegroups.com.
>>>>>>>>>>>>
>>>>>>>>>>>> For more options, visit
>>>>>>>>>>>> https://groups.google.com/groups/opt_out.
>>>>>>>>>>>
>>>>>>>>>>>

>>>>>>>>>>> --
>>>>>>>>>>> You received this message because you are subscribed to the
>>>>>>>>>>> Google Groups "Swagger" group.
>>>>>>>>>>> To unsubscribe from this group and stop receiving emails from it,

>>>>>>>>>>> send an email to swagger-swaggers...@googlegroups.com.
>>>>>>>>>>> For more options, visit https://groups.google.com/groups/opt_out.
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>> --
>>>>>>>>> You received this message because you are subscribed to a topic in
>>>>>>>>> the Google Groups "Swagger" group.
>>>>>>>>> To unsubscribe from this topic, visit
>>>>>>>>> https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.
>>>>>>>>> To unsubscribe from this group and all its topics, send an email to
>>>>>>>>> swagger-swaggers...@googlegroups.com.
>>>>>>>>> For more options, visit https://groups.google.com/groups/opt_out.
>>>>>>>>
>>>>>>>>

>>>>>>>> --
>>>>>>>> You received this message because you are subscribed to the Google
>>>>>>>> Groups "Swagger" group.
>>>>>>>> To unsubscribe from this group and stop receiving emails from it,

>>>>>>>> send an email to swagger-swaggers...@googlegroups.com.
>>>>>>>> For more options, visit https://groups.google.com/groups/opt_out.
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> You received this message because you are subscribed to a topic in
>>>>>>> the Google Groups "Swagger" group.
>>>>>>> To unsubscribe from this topic, visit
>>>>>>> https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.
>>>>>>> To unsubscribe from this group and all its topics, send an email to
>>>>>>> swagger-swaggers...@googlegroups.com.
>>>>>>> For more options, visit https://groups.google.com/groups/opt_out.
>>>>>>
>>>>>>

>>>>>> --
>>>>>> You received this message because you are subscribed to the Google
>>>>>> Groups "Swagger" group.
>>>>>> To unsubscribe from this group and stop receiving emails from it, send

>>>>>> an email to swagger-swaggers...@googlegroups.com.
>>>>>> For more options, visit https://groups.google.com/groups/opt_out.
>>>>>
>>>>>
>>>>> --
>>>>> You received this message because you are subscribed to a topic in the
>>>>> Google Groups "Swagger" group.
>>>>> To unsubscribe from this topic, visit
>>>>> https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.
>>>>> To unsubscribe from this group and all its topics, send an email to
>>>>> swagger-swaggers...@googlegroups.com.
>>>>> For more options, visit https://groups.google.com/groups/opt_out.
>>>>
>>>>
>>>
>> --
>> You received this message because you are subscribed to a topic in the
>> Google Groups "Swagger" group.
>> To unsubscribe from this topic, visit
>> https://groups.google.com/d/topic/swagger-swaggersocket/gwagTh0eHyw/unsubscribe.
>> To unsubscribe from this group and all its topics, send an email to
>> swagger-swaggers...@googlegroups.com.
>> For more options, visit https://groups.google.com/groups/opt_out.
>
>

> --
> You received this message because you are subscribed to the Google Groups
> "Swagger" group.
> To unsubscribe from this group and stop receiving emails from it, send an

[Ron]

Chris,

I'm not really aware of the mechanics of how the play integration works (yet), but generally speaking, it is not the 'adding annotations at runtime' that you want to look at but rather the process of reading those annotations. One you override that with whatever custom logic you want (and yes, you can just read from the DB to get the fields for that matter), then you are pretty much done.

Right now, we don't offer a simple way to include a attach a custom operation parameter introspection - however, you are more than welcome to open an issue about it on Swagger-Core. I can't promise it'll be implemented right away, but I should would like to see the general opinion on the matter.