Improve @requestBody

[jannyHou]

Improve @requestBody.array()

From @shimks

We should allow the parameters to take in primitive wrapper functions. This is so that users can write @requestBody.array(String, optSpec) instead of @requestBody.array({type: 'string'}, optSpec). We can leverage getSchemaForParam to do this

I have different plans for simplifying providing item's type for @requestBody.array(), and I think it takes discussion time, that's why in the first PR I just leave it as the most straight-forward syntax: providing the whole schemaSpec for array item.

Yours is one good choice! I am writing more, will update this comment then.

From @shimks

Shall we force the users to use @requestBody.array for the cases with array?

Yes!

• create shortcuts for @requestBody()
  • @requestBody.float()
  • @requestBody.binary()
    ... and more

Improve multiple contents support

From @shimks

but what do you think about allowing @requestbody to take in a string instead of an object to specify the content-type?

From @jannyHou

Good point, this goes back to my old question: what if people specify different schemas(even slightly different) for multiple content-types? While I agree with you that the object style looks redundant when shares the same schema among multiple content-types:

@requestBody({'application/json': {}, 'application/text': {}})

So I think a better way is creating a shortcut, e.g.

// not a valid code, just a concept shows the type for each parameter
@requestBody.multipleContents(
  contents: string[],
  schemaSpec:? SchemaObject , 
  otherProperties: {description?: string, required: boolean})

From @shimks

I'm going to list out the cases that requestBody may need:

• single content-type
  • schema automatically generated with application/json
    • with or without optional properties
  • schema automatically generated with explicitly set content-type
    • with or without optional properties
  • schema set by user

Now as to the cases with multiple possible content-types, I think we just leave that out of the task and create another issue for it since we're already heavily overloaded on this one anyways. If users really want to provide multiple possibly content-types for the body, they should handle it themselves anyway (imo, unless this is commonly done; it's a discussion in the other potential issue).

[jannyHou]

One more document task from this other issue, let's do it in this story together:
#1053 (comment)

We've decided to not implement these shortcuts as it's not adding much value with multiple dimensions included in the original @param.array decorator. It's not saving that much typing as well. We could document how to create shortcuts for existing decorators.

[stale]

This issue has been marked stale because it has not seen activity within six months. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository. This issue will be closed within 30 days of being stale.

[stale]

This issue has been closed due to continued inactivity. Thank you for your understanding. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository.