OpenAPI 3.0 规范中哪些位置允许使用$ref？

OpenAPI 3.0 规范中所有允许使用$ref的位置，均为规范明确定义该字段可接受「引用对象」的节点，具体清单分类如下：

路径与操作模块 #

• paths下的单个路径节点：可引用全局components.pathItems中定义的路径项
• 路径项、操作下的parameters数组的单个元素：可引用全局components.parameters中定义的参数
• 操作下的requestBody字段：可引用全局components.requestBodies中定义的请求体
• 操作responses下的单个状态码对应节点：可引用全局components.responses中定义的响应
• 操作callbacks下的单个回调节点：可引用全局components.callbacks中定义的回调

数据与内容模块 #

• 所有需要声明数据结构的位置（包括参数的schema、请求体内容的schema、响应内容的schema、头的schema等）：可引用全局components.schemas中定义的数据模型
• 参数、请求体内容、响应内容下的examples数组单个元素：可引用全局components.examples中定义的示例
• 响应下headers中的单个头节点：可引用全局components.headers中定义的响应头

其他扩展模块 #

• 响应下links中的单个链接节点：可引用全局components.links中定义的链接
• 安全规则引用的安全方案：可引用全局components.securitySchemes中定义的安全方案

额外注意：$ref遵循「引用替换原则」，一旦节点使用了$ref，该节点下所有和$ref同级的其他字段都会被规范默认忽略，不生效。此外info字段、openapi版本声明字段、paths根节点、操作的summary/description/operationId等基础属性均不支持使用$ref。

内容的提问来源于stack exchange，提问作者Ivan Yarych