如何在 Swagger UI 中显示 body 参数的嵌套数组示例？

Question

我的 POST 方法的主体中有一个嵌套数组作为参数：

 parameters:
 - in: body
   name: matrix
   description: blabla
   schema:
     type: array
     items:
       schema:
         type: array
         items:
           schema:
             type: double

我想添加一个示例，让这个数组在 Swagger UI 中可见。我尝试了以下方法，但它似乎不起作用 - 在 body 字段中没有显示任何示例。如果我在 Swagger UI 的正文字段中手动输入[[1.0, 2.0],[3.0, 4.0]]，它就可以正常工作。

 parameters:
 - in: body
   name: matrix
   description: blabla
   schema:
     type: array
     items:
       schema:
         type: array
         items:
           schema:
             type: double
   example: [[1.0, 2.0],[3.0, 4.0]]

更新：执行 Helen 的建议后，它的外观如下：

Answer 1

这是正确的版本：

  parameters:
    - in: body
      name: matrix
      description: blabla
      schema:
        type: array
        items:
          type: array
          items:
            type: number
            format: double
        example: [[1.0, 2.0],[3.0, 4.0]]

修复列表：

• schema 下不需要items。
• type: double 应该是 type: number + format: double（参见 Data Types）。
• 数组example 应与架构中的type: array 并排。参数本身不支持example 关键字。

您可以使用在线Swagger Editor 检查您的规范是否有语法错误，它会标记有错误的行。

Swagger UI 2.x 的注意事项

如果主体是基元数组，Swagger UI 2.x 不会显示主体参数示例。最新版本 Swagger UI 3.x 没有这个问题。

2.x 的一种可能的解决方法是将 x-examples.default 键添加到 body 参数并指定示例值作为字符串：

  parameters:
    - in: body
      name: matrix
      description: blabla
      schema:
        type: array
        items:
          type: array
          items:
            type: number
            format: double
        example: [[1.0, 2.0],[3.0, 4.0]]
      x-examples:
        default: '[[1.0, 2.0],[3.0, 4.0]]'  # <-----