如何在OpenAPI 3中正确定义含数组属性的响应示例

OpenAPI 3完全支持定义同时包含数组属性、字符串/数值等其他类型属性的对象响应，你碰到的Swagger UI报错是定义不符合规范导致的，共有两处核心写法错误：

• schema写法不规范
  OpenAPI 3的Schema声明必须先指定根节点的type，再通过properties字段逐个声明内部属性的类型，数组类型属性还需要通过items字段声明数组内元素的结构。直接将属性名和类型字符串平级写在schema对象下的写法，无法被Swagger等工具正确识别。
• examples结构不符合规范
  OpenAPI 3中examples字段是「示例标识-示例配置对象」的映射集合，不是直接存放响应体内容的位置，每个具体的响应示例内容必须放在对应示例配置的value字段下。直接把results、totalCount平级写在examples下时，Swagger UI会将这两个字段识别为两个独立的示例条目，触发结构校验报错。

修正后的正确定义 #

"responses": {
  "200": {
    "description": "OK",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "results": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "abc": {
                    "type": "integer"
                  }
                }
              }
            },
            "totalCount": {
              "type": "integer"
            }
          }
        },
        "examples": {
          "successResponse": {
            "summary": "查询成功示例",
            "value": {
              "results": [
                {
                  "abc": 20
                }
              ],
              "totalCount": 69
            }
          }
        }
      }
    }
  }
}

原报错截图：

内容的提问来源于stack exchange，提问作者J L