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

Question

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

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

我想添加一个示例，让这个数组在 Swagger 中可见 UI。我尝试了以下方法，但它似乎不起作用 - 正文字段中没有显示任何示例。如果我在 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]]

修复列表：

items下不需要schema。
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 键添加到正文参数并将示例值 指定为字符串 :

  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]]'  # <-----

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

How to display a nested array example for a body parameter in Swagger UI?

swagger

swagger-ui

swagger-2.0

Swagger 注释 UI 2.x