Add shortcuts for @param.array.*

[jannyHou]

Related discussion:
#1046 (comment)

Copied here:

From @bajtos :

Is it possible to preserve the old API flavour where the type could be specified as a string?

@param.array('names', 'query', 'string')
// but also
@param.array('numbers', 'query', {type: 'numer', format: 'int32'});

From @jannyHou:

@bajtos OpenAPI 3 always use a schema object to represent data structure, not like swagger 2, which uses {type: 'string'} for a simple type and {schema: {type: 'array', items: {...itemSpec}}} for a complex type.

I prefer to have some shortcuts based on the OAI3 data type common name , e.g. @param.array.string('name', 'query'), it looks a little inconsistent to me to have the 3rd decorator parameter's type as a union string | {type: string, format: string}

A full list of the shortcusts will be the same as @param.query.*:

• @param.array.integer()
• @param.array.long()
• @param.array.float()
• @param.array.double()
• @param.array.string()
• @param.array.byte()
• @param.array.binary()
• @param.array.boolean()
• @param.array.date()
• @param.array.dateTime()
• @param.array.password()

Sample pseudo code for affected lines:

// change the array decorator function to be an object with functions which fill in the schema information based on the common type:
  export const array = {
    integer: buildArray(builtinTypes.integer),
    string: buildArray(builtinTypes.string),
}

// add a utility function to build the shortcut decorators (the old array decorator function)
function buildArray(
  itemSpec: SchemaObject | ReferenceObject,
) {
  return (name: string, source: ParameterLocation) => {
      return param({
        name,
        in: source,
        schema: {type: 'array', items: itemSpec},
      });
    }
};

Acceptance Criteria:

• Add all the array decorator shortcuts for the common data types above
• Add unit tests for the shortcut decorators
• Preserve the old API to allow users to provide custom array item types not covered by our shortcuts

[bajtos]

I prefer to have some shortcuts based on the OAI3 data type common name , e.g. @param.array.string('name', 'query'), it looks a little inconsistent to me to have the 3rd decorator parameter's type as a union string | {type: string, format: string}

Fair enough 👍

I think we can close this issue as rejected.

[b-admike]

This issue is still valid and the description has been updated with more details on what needs to be done. We would need to create the decorator shortcuts for the common data types and preserve the old API for usage with custom array item types.

[virkt25]

I don't think @param.array.password() is a decorator we need.

[jannyHou]

I don't think @param.array.password() is a decorator we need.

Ah, true....

[b-admike]

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.

[jannyHou]

@b-admike I add the doc task in #1064