Swagger-如何为自由形式对象编写示例？

Question

我们有一个可能包含字段“extraInfo”的响应类型“Error”。

Error:
  type: object
  properties:
    code:
      type: string
    message:
      type: string
    extraInfo:
      description: any complementary information
      type: object
      // how to provide examples here?

一个例子是:

 "extraInfo": {
    "doors": {
      "frontLeftClosed": false,
      "frontRightClosed": true,
      "rearLeftClosed": true,
      "rearRightClosed": true,
      "trunkClosed": true
    },
    "windows": {
      "frontLeftClosed": false,
      "rearLeftClosed": true,
      "trunkClosed": false
    }
  }

另一个可能是:

"extraInfo": {
   "transactionId": "77812783001"
}

由于它是一个自由形式的对象，有没有办法在Swagger中为它提供示例？

在规范中找不到它：https://swagger.io/docs/specification/data-models/data-types/

Answer 1

使用example关键字并使用YAML或JSON对象语法指定示例值：

    extraInfo:
      description: any complementary information
      type: object
      example:   # <-------
        doors:
          frontLeftClosed: false
          frontRightClosed: true
          rearLeftClosed: true
          rearRightClosed: true
          trunkClosed: true
        windows:
          frontLeftClosed: false
          rearLeftClosed: true
          trunkClosed: false

OpenAPI 3.1(与JSON Schema 2020-12兼容)也支持模式和属性的多个< code >示例。

# openapi: 3.1.0

    extraInfo:
      description: any complementary information
      type: object
      # A list of examples
      examples:
        # Example 1
        - transactionId: '77812783001'
        # Example 2
        - doors:
            frontLeftClosed: false
            frontRightClosed: true
            rearLeftClosed: true
            rearRightClosed: true
            trunkClosed: true
          windows:
            frontLeftClosed: false
            rearLeftClosed: true
            trunkClosed: false