Swagger 在远程服务器上托管可重用组件定义，并在OpenAPI spec 3.0中将其用作$ref

我试图在OAS 3.0（OpenAPI规范3.0）中创建可重用组件定义并通过

$ref

引用它们来进行POC。我尝试了以下方法：

在我的本地机器上下载了Swagger编辑器

在我的本地计算机上创建了一个文件，其中包含我们希望跨多个API重用的公共响应

在规范中提供了该文件的引用-“$ref”：file:///path 本地目录/myreference.json“

输出不反映我引用的文件的内容。我做错什么了吗

还想知道，如果我们在一些repo（比如GitHub）上托管这样的规范，那么它们是否能够正确解析引用，并且能够被一些CMS系统获取以呈现UI

感谢您在这个问题上的指点。

嘿，桑托什

OpenAPI不支持区域设置文件系统引用的绝对路径。从 您可以看到，在您的情况下，您希望使用到您的指定位置的相对路径，对位于另一个文件夹中的文档元素尝试远程引用方法：

• 本地引用–

  $ref:“#/definitions/myElement”

  #

  表示转到当前文档的根目录，然后逐个查找元素定义和myElement
• 远程引用–

  $ref:'document.json'

  使用位于同一服务器和同一位置的整个文档。
  • 位于同一服务器上的文档元素–

    $ref:'document.json#/myElement'

  • 位于父文件夹中的文档元素–

    $ref:'../document.json#/myElement'

  • 位于另一个文件夹中的文档元素–

    $ref:'../other folder/document.json#/myElement'

• URL参考–

  $ref:'http://path/to/your/resource“

  使用位于不同服务器上的整个文档。
  • 存储在不同服务器上的文档的特定元素–$ref:“” 不同服务器上的文档，使用相同的协议（例如HTTP或HTTPS）–$ref:“//anotherserver.com/files/example.json”

---

而

$ref:file:///path

是有效的JSON引用[1]，您不应该使用它们，因为它们不可移植。相反，请使用相对引用，如中建议的，

$ref:'../relative/path/to/file.yaml'

或类似引用

$ref的原因：file:///...

在Swagger UI和Swagger Editor中不起作用，因为它们是网页，使用JavaScript解析定义，浏览器出于安全原因拒绝从JavaScript访问

文件：//

方案。

您能推荐一个可用于托管可重用定义文件的站点吗

为OpenAPI定义提供云托管。可重用组件（模式定义、响应等）可以存储在所谓的“域”文件中，并跨多个API定义使用

披露：我在一家制造“大摇大摆”的公司工作

---

[1] 根据报告：

“$ref”字符串值包含URI[]

---

和

file:///...

是有效的URI。

浏览器控制台中是否有任何错误？Helen，你好，控制台上没有错误，但它不反映编辑器中的输出。你好@lordrodos，谢谢你的回复。您能推荐一个可用于托管可重用定义文件的站点吗？您可以使用任何公开可用的托管提供商或重用您“拥有”的任何域来托管文件。我建议你的是让我们来验证你的规格。您还将获得基于ReDoc的漂亮文档预览。