Design the structure of `req.sway`

[Jeremy Whitlock]

With Sway, the structure of req.sway will likely be much simpler than in swagger-tools. As of right now, this is what I've implemented:

• api: This is the SwaggerApi object created via Sway#create
• path: This is the corresponding Path object from Sway
• operation: This is the corresponding Operation object from Sway (when available)

This means that if you want to get a parameter value, you'd do something like this: req.sway.operation.getParameter(name).value. I bring this up because @MIDUGA suggested in swagger-tools to provide simpler ways to get parameters but I'm not sure this is necessary anymore since Sway~Operation is an object with its own API.

What changes would you make?

[Jeremy Whitlock]

Well, it's still a lot to type. I could potentially add req.sway.getParam(name, [location]) that would basically be a shortcut for req.sway.operation.getParameter(name, [location]). Maybe shortcuts for all of the Operation methods make sense as well.

[Jeremy Whitlock]

What about making req.sway the Operation object?

[Nepoxx]

The main issue I have with swagger-tools right now which I personally like to see changed in sway, is that with the following req.swagger.params.myParam.value, it's not immediately clear (when looking at the controller logic) to me which one I can trust 100% to be there (to avoid something like checking ìf( req.swagger.params && req.swagger.params.myParam )).

What about making req.sway the Operation object?

Oh yes, I like the idea of doing req.sway.getParameter('myParam');

[Jeremy Whitlock]

If I make req.sway the corresponding operation, that will work just fine. Now, just so you know, Operation#getParameter returns a ParameterValue and that itself has the following getters:

• error: Returns the validation error if there is one
• raw: The raw value for the parameter
• value: The validated, coerced value

So your req.sway.getParameter('myParam') would really look like req.sway.getParameter('myParam').value. From an API perspective, this makes sense. From a middleware consumption perspective, I wonder if we can do better. Maybe we could provide access to the Sway Operation and some simpler structure for the parameters. Just know it can't be a name-based object because you can have multiple parameters with the same name but in different locations.

With that being said, I welcome any feedback.

[Miguel Ángel Durán]

I would say, the shorter the better. I'd rather prefer req.sway.getParam('myParam') to get directly the validated value as it's the most common thing that I'm going to do. Also a req.sway.getParams in order to get all of them in an object and be able to deconstruct them in a single line.

let { foo, bar } = req.sway.getParams()

[Jeremy Whitlock]

I think that's what I'm learning toward. Giving access to the Sway Operation, and by extension the rest of the Sway API, would let someone do more but making the simpler stuff quick/simple makes sense.

Thanks for the feedback.

[Miguel Ángel Durán]

Thanks to you for the great work. 👍

[Jeremy Whitlock]

Thanks for the feedback. I'll do my best to run with the feedback I have and get something solid out soon.