OpenAPI 3.0.x含鉴别器复杂JSON消息验证失败求助

可靠的在线验证工具 #

• Swagger Editor：自带OpenAPI 3.x全量校验能力，把你的OpenAPI文档粘贴进去，在/api/equipamentos的PUT请求体里输入JSON就能实时看到校验结果，不用跳转外部站点。
• OpenAPI Validator类工具：基于官方openapi-spec-validator库实现的在线工具，能精准校验请求体和schema的匹配度，找带实时校验功能的轻量工具即可。

oneOf+$type鉴别器验证失败的常见原因 #

• 鉴别器配置不完整：检查你的OpenAPI文档，oneOf对应的schema必须在discriminator里明确指定propertyName: "$type"，同时每个子schema（比如MsgAtualizacaoComputador）里要硬编码$type的固定值，示例如下：

  MsgAtualizacaoComputador:
    type: object
    properties:
      $type:
        type: string
        enum: ["MsgAtualizacaoComputador"]
      # 其他字段定义...
  

  缺少这个固定值，工具无法将JSON的$type与对应schema绑定。
• oneOf的schema顺序干扰：部分验证工具会按oneOf里的顺序匹配schema，第一个符合部分条件的就会停止校验。如果oneOf里前面的schema是MsgAtualizacaoComputador的子集，工具可能误判为匹配前一个，导致你的JSON被判定不符合目标schema。可以调整顺序，把更具体的schema放在前面。
• $type字段拼写/大小写不一致：确认JSON里的$type值和schema里enum的拼写、大小写完全一致——比如别把MsgAtualizacaoComputador写成小写开头，绝大多数验证工具是大小写敏感的。
• 子schema字段不匹配：逐字段核对MsgAtualizacaoComputador的JSON和对应的schema：有没有漏必填字段？字段类型是不是对应（比如把数字写成了字符串）？数组元素类型对不对？oneOf验证只要有一个字段不符合对应schema，就会直接失败。
• discriminator的mapping路径错误：如果用了discriminator.mapping来指定$type到schema的映射，要确保映射的schema引用路径完全正确，比如别写错components/schemas下的schema名称。

内容的提问来源于stack exchange，提问作者Luis Abreu