Design the structure of `req.sway`
whitlockjc opened this issue · comments
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 theSwaggerApi
object created viaSway#create
path
: This is the correspondingPath
object from Swayoperation
: This is the correspondingOperation
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?
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.
What about making req.sway
the Operation
object?
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')
;
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 oneraw
: The raw value for the parametervalue
: 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.
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()
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.
Thanks to you for the great work. 👍
Thanks for the feedback. I'll do my best to run with the feedback I have and get something solid out soon.