How to specify description for @param.array that will appear in the openapi explorer

[dhurtrci]

In my API I have an array query parameter. I want to give it a description that can be seen in the Open API explorer.
As the array function does not have a specific argument for description, I tried putting a description in the itemSpec.

@param.array('conditions', 'query', {
           description: 'Whatever',
           type: 'string',
           enum: Object.values(ConditionEnum)
       })

Unfortunately (and perhaps as one would expect), the generated openapi spec from this puts the description under the schema/items as illustrated below in the yml:

       - name: conditions
          in: query
          schema:
            type: array
            items:
              description: Whatever
              type: string
              enum:
                - A
                - B
                - C

To be visible in the API explorer, I need a way of getting the description to be at the top level - e.g.. :

       - name: conditions
          in: query
          description: Whatever
          schema:
            type: array
            items:
              type: string
              enum:
                - A
                - B
                - C

How do I accomplish this via the loopback decorators? Is it even possible, or is the array function maybe missing a description parameter and the necessary 'wiring' to achieve this?

[achrinza]

Hi @dhurtrci, I understand quite some time has passed since the original question has been posted, but hopefully I can still assist on this matter:

@param.array() does have some quirks that we're aware of, which would cause issues similar to the one you're observing. In this case, using @param() instead would give more control, and allow the OpenAPI 3.0 document to be generated correctly.

I believe there's already an issue on this (though I'll need to search for it), and it's something we're looking to fix at some point, albeit a lower priority as it may be a breaking change.