如何向 Swagger 響應正文添加外部密鑰

Question

我正在使用 swagger 創建一個非常簡單的快速節點 API 的文檔。 我所有的響應正文都有以下格式，使用“數據”鍵：

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

現在，我正在使用swagger-jsdoc來指定我的文檔，我的響應規范是這樣的：

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

而且，正如預期的那樣，我的大搖大擺的 UI 只顯示了帶有項目的數組，沒有我的外部對象鍵“數據”。

所以，我想知道是否可以使用 jsdoc 在 swagger UI 上表示這種模式。

Answer 1

data字段必須反映在您的響應架構中，如下所示。

此外，響應需要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

將您的定義更改為此應該可以

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