Swagger UI 将数组示例显示为 null

Question

我使用 OpenAPI 3.0.0 并希望将 Items 的数组作为参数传递给 requestBody。我的 API 定义如下所示：

post:
  tags:
    - test
  summary: Test dummy
  operationId: requestBodyTests
  requestBody:
    description: test the body
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Items'


components:
  schemas:
  Items:
    type: array
    items:
      $ref: '#/components/schemas/Item'
    examples:
      - id: bla
        text: blubb
    - id: bla
      text: blubb

  Item:
    type: object
    properties:
      id:
        type: string
      name:
        type: string

Swagger UI显示请求正文示例如下：

请求正文架构如下：

为什么它显示的是有序地图而不是我的普通对象？

有人能告诉我如何做正确的规范以使包含项目的数组正确吗？

Answer 1

模式中的示例使用 example 关键字（单数），而不是 examples（复数）。

此外，您的 YAML 缩进错误 - Items 和 Item 必须在 schemas 下缩进，示例中的列表项必须具有相同的缩进等。如果您粘贴你的规范进入 http://editor.swagger.io，它会指出语法错误。

这是固定版本：

components:
  schemas:
    Items:
      type: array
      items:
        $ref: '#/components/schemas/Item'
      example:   # <------
        - id: bla
          text: blubb
        - id: bla
          text: blubb

    Item:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

Answer 2

此外，您得到一个示例 'orderedmap' 因为示例字段是 A free-form 属性。但是表示无法在 JSON 或 YAML 中自然表示的示例，可以使用字符串值来包含示例，并在必要时进行转义。 (OpenAPI spec)

我们可以用两种方式写一个例子'string'：

1.

example: '[ currency: USD, amount: 123 ]'

  example: |
    [ 
      currency: USD, 
      amount: 123 
    ]

Swagger UI 将数组示例显示为 null

Swagger UI displaying array example as null

swagger

swagger-ui

openapi