移除引用
有时，在 OpenAPI 描述 (OAD) 中移除引用很有用。一个常见的用例是与不理解引用的工具配合使用。然而，这并不总是直观的，本页介绍了需要注意的主要点。
将 OAD 转换为不含任何引用的单文档形式
并非所有 OAD 都可以转换，但在许多情况下，可以在不出现问题的情况下进行转换。
困难的情况包括
- JSON Schema 中的循环引用**无法**移除，尽管如果引用跨文档，则可以将它们缩减为单个文档中的相同文档引用
- 虽然 OAS 3.1 Schema 对象中的动态引用从技术上讲可以转换为静态引用，但它可能会以指数方式增加模式大小 (pdf)
- OAS 3.1 Schema 对象、OAS 3.0 引用对象以及 OAS 3.0 和 3.1 路径项对象都允许在
"$ref"旁边使用关键字，每个关键字的语义略有不同；通用的引用移除工具，尤其是那些在 OAS 3.1 之前的工具，可能会在移除引用时无法保留行为 - 在使用
"$id"的 OAS 3.1 Schema 对象中，没有意识到"$id"的引用移除工具会错误地解析受"$id"影响的引用 - 链接对象的
"operationRef"无法替换为内联操作对象（尽管如果目标操作对象在 OAD 中具有唯一的"operationId"，那么"operationRef"可以替换为"operationId"） - 鉴别器对象的
"mapping"字段禁止内联 Schema 对象；URI 引用值可以用组件对象的"schemas"部分中的名称替换，但当鉴别器对象在引用的文档中时，如何解析这些名称存在歧义 - 当使用由标准组织等第三方发布的组件时，工具可能会依赖于引用 URI 来识别标准组件；虽然此用法目前不常见，但随着 OpenAPI 被更多标准机构采用，它可能会变得更加普遍
如果您的 OAD 没有违反上述任何困难，那么您可以生成一个无引用的单文档 OAD，并且有一些工具可以做到这一点（但请参阅下一节中的注意事项）。
将多文档 OAD 转换为单文档
即使无法移除所有引用，也可以将多文档 OAD 转换为单文档。但是，具体取决于您的多文档 OAD 的结构方式，这可能比仅仅移除引用更复杂。遗憾的是，原因在于关于如何解析多文档 OAD 的令人痛苦地模糊和技术上的歧义。OpenAPI Initiative 希望在规范的未来版本中澄清这一点。
- 链接对象的
"operationId"可以指向路径项对象中从不引用的操作对象；不清楚此情况应如何处理，这也是 OAS 本身建议不要在多文档 OAD 中使用"operationId"的原因之一 - 安全方案对象从不引用，只在安全需求对象中命名，必须予以考虑
- 在 OAS 3.0 中，没有标准位置可以放置引用的路径项对象
- 在多文档 OAD 中，服务器配置和安全设置的解析可能不明确
同样，在许多情况下，这些都没有问题，并且有一些工具可以满足您的需求。