为何OpenAPI未将$ref定义为允许属性？验证失败问题咨询

这确实是个容易让人困惑的点，先给你明确结论——这大概率不是笔误，而是OpenAPI规范和JSON Schema draft-07之间的核心差异导致的。

为什么会出现验证失败？ #

JSON Schema draft-07会把$ref定义为schema的一个属性（就像你给出的示例那样），但OpenAPI的Schema Object虽然基于JSON Schema，却有自己的专属规则：$ref在OpenAPI里是一个顶级关键字，不属于properties的范畴，所以OpenAPI的元schema不会将$ref列为允许的属性项。谷歌API提供的OpenAPI schema是遵循OpenAPI规范编写的，自然不会把$ref放在properties里定义。

检查$ref属性的实用建议 #

• 严格遵循OpenAPI的$ref规则：
  • $ref的值必须是符合uri-reference格式的字符串，比如#/components/schemas/User这种内部引用，或者外部URI。
  • 注意$ref不能和其他schema关键字共存（除了$comment这种辅助关键字），一旦使用$ref，当前schema的其他属性都会被忽略。
• 使用OpenAPI专属验证工具：
  不要用普通的JSON Schema验证器来校验OpenAPI文档，推荐用专门的工具，比如openapi-cli、spectral或者Redocly的验证工具，它们能识别OpenAPI特有的规则，正确处理$ref的校验。
• 匹配正确的OpenAPI版本：
  确认你使用的OpenAPI版本（3.0 vs 3.1），OpenAPI 3.1更贴近JSON Schema draft-2020-12，而3.0和draft-07的差异更大。谷歌的API文档可能基于特定版本编写，要保证你的验证器和目标版本一致。
• 手动排查引用有效性：
  逐一检查$ref的引用路径是否正确，比如拼写错误、引用的schema是否存在于components/schemas（或对应位置）中，避免出现无效引用导致的验证问题。

内容的提问来源于stack exchange，提问作者Eugen Konkov