swagger-uiopenapiswagger-jsdocs

How to add a external key to Swagger response bodies


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.


Solution

  • 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'