在 OpenAPI 描述中使用引用

OpenAPI 引用是一个强大的工具。它允许管理文档的大小和复杂度，并允许重用共享组件，避免复制粘贴或更改管理错误。

但是，引用的历史和 "$ref" 关键字很复杂，导致根据您使用的 OpenAPI 规范 (OAS) 版本以及在 OpenAPI 描述 (OAD) 中引用出现的位置，其行为略有不同。还有其他 "$ref" 类似的关键字（"operationRef"、"mapping"）和行为（按组件名称或操作 ID 引用），这些关键字和行为相关但略有不同。由于不同工具之间的支持不完整且不一致，引用也可能难以使用，其中一些工具需要在读取 OAD 之前对引用进行预处理。

本节中的资源解释了如何使用引用以及在评估 OpenAPI 工具中的引用支持时要寻找什么。

引用的未来

计划在未来的 OpenAPI 规范中减少围绕引用的复杂性。

该 Moonwalk 项目 正在考虑一种不同的方法，该方法导入完整的文档，将它们与命名空间关联，并且只支持按组件名称引用（而不是 "$ref"）。在 Moonwalk 部署建议 中可以看到一个小的示例，并且围绕 导入的初步草案建议 以及一些关于 如何管理与 JSON Schema 引用交互 的想法正在进行讨论。

该 建议的工作流程规范 已经使用了一个 "sourceDescription" 字段，它与 Moonwalk 建议类似。