Swagger UI引用外部JSON Schema文件出现Unknown Type报错问题

• OpenAPI components结构不符合规范。OpenAPI 3.x标准要求components下的schema定义必须放在schemas子节点下，你当前直接在components下写NotificationGroup属于语法错误，会导致解析器读取字段类型异常。
• OpenAPI版本和JSON Schema特性不兼容。OpenAPI 3.0及以下版本不支持JSON Schema中type: ["object", "null"]这种联合类型写法，遇到这类写法时解析器会将数组内容拼接为object,null识别，抛出未知类型错误。
• VS Code的「OpenAPI SwaggerUI preview」插件本身的跨文件引用解析存在缺陷，即使路径正确也可能出现外部JSON Schema读取异常的问题。

• 修正components层级结构，将模型定义放到schemas子节点下，正确写法参考：

components:
  schemas:
    NotificationGroup:
      type: object
      properties:
        eligibilityNotifications:
          type: array
          items:
            $ref: '../JSONSchemas/foo.json#/definitions/EligibilityNotification'

• 匹配OpenAPI版本调整JSON Schema写法：
  • 如果使用OpenAPI 3.0版本，移除JSON Schema中type数组里的null值，给需要可空的字段添加nullable: true属性。
  • 如果需要保留JSON Schema中的null类型，将Swagger文件开头的OpenAPI版本声明改为3.1及以上版本。
• 替换预览插件：改用VS Code的「OpenAPI (Swagger) Editor」插件，该插件对跨文件$ref的兼容性更好，可避免解析bug。
• 检查外部JSON Schema语法：确认foo.json中没有语法错误，所有字段定义符合对应JSON Schema版本规范。

内容的提问来源于stack exchange，提问作者Xavier W.