如何在Swagger UI中展示复杂嵌套整数数组结构？

核心思路 #

针对你这种多层嵌套的整数数组结构，需要在OpenAPI 3.0规范里用**type: array结合items**字段逐层定义嵌套层级，每一层数组都通过items指定下一级的结构。

具体实现步骤 #

1. 用swagger-jsdoc定义Schema #

在你的接口注释里，通过@swagger标签按层级定义raw_data的结构：

/**
 * @swagger
 * /your-post-endpoint:
 *   post:
 *     summary: 提交包含复杂嵌套整数数组的请求
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               raw_data:
 *                 type: array
 *                 description: 多层嵌套的整数数组
 *                 items:
 *                   type: array
 *                   items:
 *                     oneOf:
 *                       - type: array
 *                         items:
 *                           type: integer
 *                       - type: array
 *                         items:
 *                           type: array
 *                           items:
 *                             type: integer
 *             example:
 *               raw_data:
 *                 - [[1,2], [4,5], [7,8]]
 *                 - [[[1,2], [4,5], [7,8]]]
 */

2. 关键细节说明 #

• 因为你的raw_data数组里的元素有两种嵌套层级（二级数组和三级数组），所以用oneOf兼容两种结构场景。
• 每一层数组都要明确type: array，并通过items指定下一级类型：
  • 最内层是type: integer的数组；
  • 中间层是包含整数数组的数组；
  • 外层是包含上述两种数组的数组。
• 添加example字段可以让Swagger UI直接展示你提供的示例结构，更直观。

验证效果 #

启动Node服务后，访问Swagger UI页面（默认路径是/api-docs），找到对应的POST接口，展开请求体部分就能看到定义好的嵌套数组结构，还能直接用示例值发起测试请求。

内容的提问来源于stack exchange，提问作者Momo