OpenAPI 3.0如何定义支持接收字节数组或对象(哈希映射)的字段

报错原因 #

你的写法触发报错的核心问题是在字段根级额外声明了type: object，该强制限定和anyOf中的字节数组分支直接冲突，导致永远无法满足校验规则。同时你定义字节数组时直接写type: byte不符合OpenAPI的规范要求。

修正后的标准写法 #

兼容OpenAPI 3.0+版本写法 #

oldResource:
  description: Old Resource map/byte array
  anyOf:
    # 哈希映射类型分支
    - type: object
      additionalProperties: true # 明确是任意键值的哈希映射，如有固定字段可替换为properties定义
    # 字节数组类型分支
    - type: array
      items:
        type: string
        format: byte # OpenAPI标准字节定义，对应Base64编码的字节序列

如果你需要定义元素为0-255数值的原生字节数组，可将数组分支调整为：

- type: array
  items:
    type: integer
    format: int32
    minimum: 0
    maximum: 255

OpenAPI 3.1+简化写法 #

3.1及以上版本支持直接声明多个type，写法更简洁：

oldResource:
  description: Old Resource map/byte array
  type:
    - object
    - array
  additionalProperties: true # 哈希映射规则
  items: # 字节数组规则
    type: string
    format: byte

内容的提问来源于stack exchange，提问作者Prateek Narendra