How to add a external key to Swagger response bodies

Question

I am using swagger to create docs of a very simple express node API. All my response bodies have the follow format, using the "data" key:

{
  "data": [items] // or a single item if it is the case
}

Right now, I'm using swagger-jsdoc to specify my docs, and my responses specifications are like this:

*   responses:
*     200:
*       content:
*         application/json:
*           schema:
*             type: array
*               items:
*                 $ref: '#/components/schemas/Item'

And, like expected, my swagger UI shows just the array with an Item, without my external object key "data".

So, I would like to know if it is possible to represente this pattern on swagger UI using jsdoc.

Answer 1

The data field must be reflected in your response schema, as shown below.

Also, responses require a description.

*   responses:
*     '200':
*       description: A list of Foos   # <---
*       content:
*         application/json:
*           schema:
*             type: object      # <---
*             properties:       # <---
*               data:           # <---
*                 type: array
*                 items:
*                   $ref: '#/components/schemas/Item'

Answer 2

Changing your definition to this should work

    get:
      summary: Your GET endpoint
      tags: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Items'