Swagger

Question

我们有一个响应类型“错误”，它可能包含一个字段“extraInfo”。

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 兼容）还支持多个 examples 模式和属性。

# 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

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

Swagger - How to write an example for a Free-Form Object?

openapi