OpenAPI文档中非URI安全字符串的引用编码规范问询

标准做法：按JSON Pointer规则来 #

OpenAPI里用$ref引用内部元素时，得遵循**JSON Pointer（RFC 6901）**的编码规则，不是普通的URL编码。具体规则很明确：

• 把路径里的/替换成~1
• 要是内容本身有~，就得换成~0

比如你说的例子：从/path/two的default响应引用/path/one的default响应，正确的引用应该写成这样：

paths:
  /path/two:
    get:
      responses:
        default:
          $ref: '#/paths/~1path~1one/get/responses/default'

这里的~1path~1one就是对/path/one的正确编码——每个/都换成了~1。

用~直接替换/符合标准吗？ #

完全不符合。你看到的那种单个~代替/的写法是错的，不属于OpenAPI或JSON Pointer的规范。在JSON Pointer里，只有~1才对应原始的/，单独的~没有特殊含义，这种引用会被解析器当成无效路径，根本找不到目标元素。

为啥会有这种错误写法？ #

大概率是文档作者搞混了JSON Pointer编码和其他自定义规则，或者是工具生成时出了bug。apis.guru上的个别文档可能存在不规范的情况，但这不能代表它是对的。

内容的提问来源于stack exchange，提问作者Balázs Édes